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1. Introduction 

2. What is Sugar? 

3. What is a Sugar Activity? 

4. What Do I Need To Know To Write A Sugar Activity? 



A • Introduction 



"This book is a record of a pleasure trip. If it were a record of a solemn scientific 
expedition, it would have about it that gravity, that profundity, and that impressive 
incomprehensibility which are so proper to works of that kind, and withal so attractive." 

From the Preface to The Innocents Abroad, by Mark Twain 

The purpose of this book is to teach you what you need to know to write Activities for 
Sugar, the operating environment developed for the One Laptop Per Child project. This 
book does not assume that you know how to program a computer, although those who 
do will find useful information in it. My primary goal in writing it is to encourage non 
programmers, including children and their teachers, to create their own Sugar 
Activities. Because of this goal I will include some details that other books would leave 
out and leave out things that others would include. Impressive incomprehensibility will 
be kept to a minimum. 

If you just want to learn how to write computer programs Sugar provides many 
Activities to help you do that: Etoys, Turtle Art, Scratch, and Pippy None of these are 
really suitable for creating Activities so I won't cover them in this book, but they're a 
great way to leam about programming. If you decide after playing with these that you'd 
like to try writing an Activity after all you'll have a good foundation of knowledge to 
build on. 

When you have done some programming then you'll know how satisfying it can be to 
use a program that you made yourself, one that does exactly what you want it to do. 
Creating a Sugar Activity takes that enjoyment to the next level. A useful Sugar 
Activity can be translated by volunteers into every language, be downloaded hundreds 
of times a week and used every day by students all over the world. 
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A book that teaches everything you need to know to write Activities would be really, 
really long and would duplicate material that is already available elsewhere. B ecause of 
this, I am going to write this as sort of a guided tour of Activity development. That 
means, for example, that I'll teach you what Python is and why it's important to learn it 
but I won't teach you the Python language itself. There are excellent tutorials on the 
Internet that will do that, and I'll refer you to those tutorials. 

There is much sample code in this book, but there is no need for you to type it in to try 
it out. All of the code is in a Git repository that you can download to your own 
computer. If you've never used Git there is a chapter that explains what it is and how to 
use it. 



I started writing Activities shortly after I received my XO laptop. When I started I didn't 
know any of the material that will be in this book. I had a hard time knowing where to 
begin. What I did have going for me though was a little less than 30 years as a 
professional programmer. As a result of that I think like a programmer. A good 
programmer can take a complex task and divide it up into manageable pieces. He can 
figure out how things must work, and from that figure out how they do work. He knows 
how to ask for help and where. If there is no obvious place to begin he can begin 
somewhere and eventually get where he needs to go. 



Because I went through this process I think I can be a pretty good guide to writing 
Sugar Activities. Along the way I hope to also teach you how to think like a 
programmer does. 

From time to time I may add chapters to this book. Sugar is a great application platform 
and this book can only begin to tell you what is possible. It is my hope that future 
versions of the book will have guest chapters on more advanced topics written by other 
experienced Activity developers. 



Za • What is Sugar? 



Sugar is the user interface designed for the XO laptop. It can now be installed on most 
PCs, including older models that can't run the latest Windows software. You can also 
install it on a thumb drive (Sugar on a Stick) and boot your PC from that. 

When the XO laptop first came out some people questioned the need for a new user 
interface. Wouldn't it be better for children to learn something more like what they 
would use as adults? Why not give them Microsoft Windows instead? 

This would be a reasonable question if the goal was to train children to use computers 
and nothing else. It would be even more reasonable if we could be sure that the 
software they would use as adults looked and worked like the Microsoft Windows of 
today. These are of course not reasonable assumptions. 

The OLPC project is not just about teaching computer literacy. It is about teaching 
everything: reading, writing, arithmetic, history, science, arts and crafts, computer 
programming, music composition, and everything else. Not only do we expect the child 
to use the computer for her school work, we expect her to take it home and use it for her 
own explorations into subjects that interest her. 

This is a great deal more than anyone has done with computers for education, so it is 
reasonable to rethink how children should work with computers. Sugar is the result of 
that rethinking. 

Sugar has the following unique features: 

The Journal 

The Journal is where all the student's work goes. Instead of files and folders there is a 
list of Journal entries. The list is sorted in descending order by the date and time it was 
last worked on. In a way it's like the "Most Recently Used" document menu in 
Windows, except instead of containing just the last few items it contains everything and 
is the normal way to save and resume work on something. 



The Journal makes it easy to organize your work. Any work you do is saved to the 
Journal. Anything you download from the web goes in the Journal. If you've ever 
downloaded a file using a web browser, then had to look for it afterwards because it 
went in some directory other than the one you expected, or if you ever had to help your 
parents when they were in a similar situation, you can understand the value of the 
Journal. 

The Journal has metadata for each item in it. Metadata is information about information. 
Every Journal entry has a title, a description, a list of keywords, and a screen shot of 
what it looked like the last time it was used. It has an activity id that links it to the 
Activity that created it, and it may have a MIME type as well (which is a way of 
identifying Journal entries so that items not created by an Activity may still be used by 
an Activity that supports that MIME type). 

In addition to these common metadata items a Journal entry may be given custom 
metadata by an Activity. For instance, the Read Activity uses custom metadata to save 
the page number you were reading when you quit the Activity. When you resume 
reading later the Activity will put you on that page again. 

In addition to work created by Activities, the Journal can contain Activities themselves. 
To install an Activity you can use the Browse Activity to visit the website 
http : //activities . sugarlab s . org and download it. It will automatically be saved to the 
Journal and be ready for use. If you don't want the Activity any more, simply delete it 
from the Journal and it's completely gone. No uninstall programs, no dialog boxes telling 
you that such and such a .DLL doesn't seem to be needed anymore and do you want to 
delete it? No odd bits and pieces left behind. 

Collaboration 

The second unique feature Sugar is Collaboration. Collaboration means that Activities 
can be used by more than one person at the same time. While not every Activity needs 
collaboration and not every Activity that could use it supports it, a really first rate 
Activity will provide some way to interact with other Sugar users on the network. For 
instance, all the e-book reading Activities provide a way of giving a copy of the book 
you're reading (with any notes you added to it) to a friend or to the whole class. The 
Write Activity lets several students work on the same document together. The 
Distance Activity lets two students see how far apart from each other they are. 

There are five views of the system you can switch to at the push of a button (Function 
Keys Fl-4). They are: 



• The Neighborhood View 

• The Friends View 

• The Activity Ring 

• The Journal 

Of these Views, the first two are used for Collaboration. 

The Neighborhood View shows icons for everyone on the network. Every icon looks 
like a stick figure made by putting an "O" above an "X". Each icon has a name, chosen 
by the student when she sets up her computer. Every icon is displayed in two colors, 
also chosen by the student. In addition to these "XO" icons there will be icons 
representing mesh networks and others representing WiFi hot spots. Finally there will 
be icons representing active Activities that their owners wish to share. 

To understand how this works consider the Chat Activity. The usual way applications 
do chat is to have all the participants start up a chat client and visit a particular chat 
room at the same time. With Sugar it's different. One student starts the Chat Activity on 
her own computer and goes to the Neighborhood View to invite others on the network 
to participate. They will see a Chat icon in their own Neighborhood View and they can 
accept. The act of accepting starts up their own Chat Activity and connects them to the 
other participants. 

The Friends View is similar to the Neighborhood View, but only contains icons for 
people you have designated as Friends. Collaboration can be offered at three levels: with 
individual persons, with the whole Neighborhood, and with Friends. Note that the 
student alone decides who her Friends are. There is no need to ask to be someone's 
Friend. It's more like creating a mailing list in email. 

Security 

Protecting computers from malicious users is very important, and if the computers 
belong to students it is doubly important. It is also more difficult, because we can't 
expect young students to remember passwords and keep them secret. Since Sugar runs 
on top of Linux viruses aren't much of a problem, but malicious Activities definitely are. 
If an Activity was allowed unrestricted access to the Journal, for instance, it could wipe it 
out completely. Somebody could write an Activity that seems to be harmless and 
amusing, but perhaps after some random number of uses it could wipe out a student's 
work. 



The most common way to prevent a program from doing malicious things is to make it 
run in a sandbox. A sandbox is a way to limit what a program is allowed to do. With the 
usual kind of sandbox you either have an untrusted program that can't do much of 
anything or a trusted program that is not restricted at all. An application becomes 
trusted when a third party vouches for it by giving it a signature. The signature is a 
mathematical operation done on the program that only remains valid if the program is 
not modified. 

Sugar has a more sophisticated sandbox for Activities than that. No Activity needs to be 
trusted or is trusted. Every Activity can only work with the Journal in a limited, indirect 
way. Each Activity has directories specific to it that it can write to, and all other 
directories and files are limited to read-only access. In this way no Activity can interfere 
with the workings of any other Activity. In spite of this, an Activity can be made to do 
what it needs to do. 

Summary 

Sugar is an operating environment designed to support the education of children. It 
organizes a child's work without needing files and folders. It supports collaboration 
between students. Finally, it provides a robust security model that prevents malicious 
programs from harming a student's work. 

It would not be surprising to see these features someday adopted by other desktop 
environments. 
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A Sugar Activity is a self-contained Sugar application packaged in a .xo bundle. 
An .xo bundle is an archive file in the Zip format. It contains: 

• A MANIFEST file listing everything in the bundle 

• An activity.info file that has attributes describing the Activity as name=value 
pairs. These attributes include the Activity name, its version number, an identifier, 
and other things we will discuss when we write your first Activity. 

• An icon file (in SVG format) 

• Files containing translations of the text strings the Activity uses into many 
languages 

• The program code to run the Activity 

A Sugar Activity will generally have some Python code that extends a Python class 
called Activity. It may also make use of code written in other languages if that code is 
written in a way that allows it to be used from Python (this is called having Python 
bindings). It is even possible to write a Sugar Activity without using Python at all, but 
this is beyond the scope of this book. 

There are only a few things that an Activity can depend on being included with every 
version of Sugar. These include modules like Evince (PDF and other document 
viewing), Gecko (rendering web pages), and Python libraries like PyGTK and PyGame. 
Everything needed to run the Activity that is not supplied by Sugar must go in the 
bundle file. A question sometimes heard on the mailing lists is "How do I make Sugar 
install X the first time my Activity is run?" The answer: you don't. If you need X it 
needs to go in the bundle. 

You can install an Activity by copying or downloading it to the Journal. You uninstall it 
by removing it from the Journal. There is no Install Shield to deal with, no deciding 
where you want the files installed, no possibility that installing a new Activity will make 
an already installed Activity stop working. 

An Activity generally creates and reads objects in the Journal. A first rate Activity will 
provide some way for the Activity to be shared by multiple users. 



4 • What Do I Need To Know To Write A 
Sugar Activity? 

If you are going to write Sugar Activities you should learn something about the topics 
described in this chapter. There is no need to become an expert in any of them, but you 
should bookmark their websites and skim through their tutorials. This will help you to 
understand the code samples we'll be looking at. 

Python 

Python is the most used language for writing Activities. While you can use other 
languages, most Activities have at least some Python in them. Sugar provides a Python 
API that simplifies creating Activities. While it is possible to write Activities using no 
Python at all (like Etoys), it is unusual. 

All of the examples in this book are written entirely in Python. 

There are compiled languages and interpreted languages. In a compiled language the 
code you write is translated into the language of the chip it will run on and it is this 
translation that is actually run by the OS. In an interpreted language there is a program 
called an interpreter that reads the code you write and does what the code tells it to do. 
(This is over simplified, but close enough to the truth for this chapter). 

Python is an interpreted language. There are advantages to having a language that is 
compiled and there are advantages to having an interpreted language. The advantages 
Python has for developing Activities are: 
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• It is portable. In other words, you can make your program run on any chip and 
any OS without making a version specific to each one. Compiled programs only 
run on the OS and chip they are compiled for. 

• Since the source code is the thing being run, you can't give someone a Python 
program without giving them the source code. You can learn a lot about Activity 
programming by studying other people's code, and there is plenty of it to study. 

• It is an easy language for new programmers to learn, but has language features that 
experienced programmers need. 

• It is widely used. One of the best known Python users is Google. They use it 
enough that they have started a project named "Unladen Swallow" to make 
Python programs run faster. 

The big advantage of a compiled language is that it can run much faster than an 
interpreted language. However, in actual practice a Python program can perform as well 
as a compiled program. To understand why this is you need to understand how a 
Python program is made. 

Python is known as a "glue" language. The idea is that you have components written in 
various languages (usually C and C++) and they have Python bindings. Python is used 
to "glue" these components together to create applications. In most applications the 
bulk of the application's function is done by these compiled components, and the 
application spends relatively little time running the Python code that glues the 
components together. 

In addition to Activities using Python most of the Sugar environment itself is written in 
Python. 

If you have programmed in other languages before there is a good tutorial for learning 
Python at the Python website: http : //docs. python. org/tutorial/ . If you're just starting 
out in programming you might check out Invent Your Own Computer Games With 
Python, which you can read for free at http://inventwithpython.com/ . 

PyGTK 

GTK+ is a set of components for creating user interfaces. These components include 
things like buttons, scroll bars, list boxes, and so on. It is used by GNOME desktop 
environment and the applications that run under it. Sugar Activities use a special 
GNOME theme that give GTK+ controls a unique look. 
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PyGTK is a set of Python bindings that let you use GTK+ components in Python 
programs. There is a tutorial showing how to use it at the PyGTK website: 
http : //www.py gtk. org/tutorial. html . 

PyGame 

The alternative to using PyGTK for your Activity is PyGame. PyGame can create 
images called sprites and move them around on the screen. As you might expect, 
PyGame is mostly used for writing games. It is less commonly used in Activities than 
PyGTK. 

The tutorial to learn about PyGame is at the PyGame website: 

http://www.pygame.org/wiki/tutorials . The website also has a bunch of pygame projects 
you can download and try out. 
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3 • Setting Up a Sugar Development 
Environment 

It is not currently practical to develop Activities for the XO on the XO. It's not so much 
that you can't do it, but that it's easier and more productive to do your development 
and testing on another machine running a more conventional OS. This gives you access 
to better tools and it also enables you to simulate collaboration between two computers 
running Sugar using only one computer. 

Install Linux Or Use A Virtual Machine? 

Even though Sugar runs on Linux it is possible to run a complete instance of Sugar in a 
virtual machine that runs on Windows. A virtual machine is a way to run one operating 
system on top of another one. The operating system being run is fooled into thinking it 
has the whole computer to itself. (Computer industry pundits will tell you that using 
virtual machines is the newest new thing out there. Old timers like me know that IBM 
was doing it on their mainframe computers back in the 1970's). 

For awhile this was actually the recommended way to develop Activities. The version of 
Linux that Sugar used was different enough from regular Linux distributions that even 
Linux users were running Sugar in a virtual machine on top of Linux. 

The situation has improved, and most current Linux distributions have a usable Sugar 
environment. 

If you're used to Windows you might think that running Sugar in a VM from Windows 
instead of installing Linux might be the easier option. In practice it is not. Linux running 
in a VM is still Linux, so you're still going to have to learn some things about Linux to 
do Activity development. Also, running a second OS in a VM requires a really powerful 
machine with gigabytes of memory. On the other hand, I do my Sugar development 
using Linux on an IBM NetVista Pentium IV I bought used for a little over a hundred 
dollars, shipping included. It is more than adequate. 

Installing Linux is not the test of manhood it once was. Anyone can do it. The GNOME 
desktop provided with Linux is very much like Windows so you'll feel right at home 
using it. 
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When you install Linux you have the option to do a dual boot, running Linux and 
Windows on the same computer (but not at the same time). This means you set aside a 
disk partition for use by Linux and when you start the computer a menu appears asking 
which OS you want to start up. The Linux install will even create the partition for you, 
and a couple of gigabytes is more than enough disk space. Sharing a computer with a 
Linux installation will not affect your Windows installation at all. 

Sugar Labs has been working to get Sugar included with all Linux distributions. If you 
already have a favorite distribution, chances are the latest version of it includes Sugar. 
Fedora, openSuse, Debian, and Ubuntu all include Sugar. If you already use Linux, see 
if Sugar is included in your distribution. If not, Fedora is what is used by the XO 
computer so Fedora 10 or later might be your best bet. You can download the Fedora 
install CD or DVD here: https://fedoraproject.org/get-fedora . 

It is worth pointing out that all of the other tools I'm recommending are included in 
every Linux distribution, and they can be installed with no more effort than checking a 
check box. The same tools often will run on Windows, but installing them there is more 
work than you would expect for Windows programs. 

If you are unwilling to install and learn about Linux but still want to develop Activities 
one option you have is to develop a standalone Python program that uses PyGame of 
PyGTK and make it do what you'd like your Activity to do. You could then turn over 
your program to someone else who could convert it into a Sugar Activity. You could 
develop such a Python program on Windows or on the Macintosh. 

If you want to do development on a Macintosh running Sugar in a virtual machine may 
be a more attractive option. If you want to try it details will be found here: 
http : //wiki. laptop. org/go/D ev elopers/Setup. It may also be possible to install Fedora 
Linux on an Intel or Power PC Macintosh as a dual boot, just like you can do with 
Windows. Check the Fedora website for details. 

Another option for Mac users is to use Sugar on a Stick as a test environment. You can 
learn about that here: http://wiki.sugarlabs.org/go/Sugar on a Stick . 
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What About Using sugar-jhbuild? 

Sugar-jhbuild is a script that downloads the source code for the latest version of all the 
Sugar modules and compiles it into a subdirectory of your home directory. It doesn't 
actually install Sugar on your system. Instead, you run it out of the directory you 
installed it in. Because of the way it is built and run it doesn't interfere with the 
modules that make up your normal desktop. If you are developing Sugar itself, or if you 
are developing Activities that depend on the very latest Sugar features you'll need to 
run sugar-jhbuild. 

Running this script is a bit more difficult than just installing the Sugar packages that 
come with the distribution. You'll need to install Git and Subversion, run a Git 
command from the terminal to download the sugar-jhbuild script, then run the script 
with several different options which download more code, ask you to install more 
packages, and ultimately compile everything. It may take you a couple of hours to do 
all the steps. When you're done you'll have an up to date test environment that you can 
run as an alternative to sugar-emulator. There is no need to uninstall sugar-emulator; 
both can coexist. 

You run it with these commands: 

cd sugar-jhbuild 

./sugar-jhbuild run sugar-emulator 

Should you consider using it? The short answer is no. A longer answer is probably not 
yet. 

If you want your Activities to reach the widest possible audience you don 't want the 
latest Sugar. In fact, if you want a test environment that mimics what is on most XO 
computers right now you need to use Fedora 10. Because updating operating systems in 
the field can be a major undertaking for a school most XO's will be running Sugar .82 or 
older for quite some time. 

Of course it is also important to have developers that want to push the boundaries of 
what Sugar can do. If after developing some Activities you decide you need to be one of 
them you can learn about running sugar-jhbuild here: 
http://wiki.sugarlabs.org/go/DevelopmentTeam/Jhbuild. 

Strictly speaking sugar-jhbuild is just the script that downloads and compiles Sugar. If 
you wanted to be correct you would say "Run the copy of sugar-emulator you made 
with sugar-jhbuild". Most Sugar developers would just say "Run sugar-jhbuild" and 
that's what I'll say in this book. 
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Python 

We'll be doing all the code samples in Python so you'll need to have Python installed. 
Python comes with every Linux distribution. You can download installers for Windows 
and the Macintosh at http : 1 1 www, python, org/ . 

Eric 

Developers today expect their languages to be supported by an Integrated 
Development Environment and Python is no exception. An IDE helps to organize 
your work and provides text editing and a built in set of programming and debugging 
tools. 
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There are two Python IDE's I have tried: Eric and Idle. Eric is the fancier of the two and 
I recommend it. Every Linux distribution should include it. It looks like it might work 
on Windows too. You can learn more about it at the Eric website: http : //eric-ide . py thon- 
projects.org/ . 
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SPE (Stani's Python Editor) 



This is an IDE I discovered while writing this book. It comes with Fedora and in 
addition to being a Python editor it will make UML diagrams of your code and show 
PyDoc for it. Here is SPE showing a UML diagram for one of the Activities in this 
book: 
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If you're an experienced developer you might find this a useful alternative to Eric. If 
you're just starting out Eric should meet your needs pretty well. 

Other IDE's 

There is also a commercial Python IDE called Wingware, which has a version you can 
use for free. You can learn more about it at http://www.wingware.com/ . 
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Inkscape 

Inkscape is a tool for creating images in SVG format. Sugar uses SVG for Activity icons 
and other kinds of artwork. The "XO" icon that represents each child in the 
Neighborhood view is an SVG file that can be modified. 
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Inkscape comes with every Linux distribution, and can be installed on Windows as 
well. You can learn more about it here: http: //www. inkscape . org/ . 
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Git 

Git is a version control system. It stores versions of your program code in a way that 
makes them easy to get back. Whenever you make changes to your code you ask Git to 
store your code in its repository. If you need to look at an old version of that code later 
you can. Even better, if some problem shows up in your code you can compare your 
latest code to an old, working version and see exactly what lines you changed. 

readtrjolbar.py 
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IB M along with this program; it not, write to the Free Software 

16 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 92119-1391 

17 

18 import os 

19 import logging 

20 from gettext import gettext as 

21 import re 

combotool.show() 

self .pitchadj = gtk. Adjustment (B, -ISO, ISO, 1, IB, 0) 

self .pitchadj . connect ("value_changed", self .pitch_adjusted_cb) 

pitchbar = gtk. HScale(self .pitchadj) 

pitchbar , set_draw_value(False) 

pitchbar. set_update_policjf (gtk. UPDATE_DISCDNTINU0US) 



pitchbar, show() 

self.rateadj = gtk, Adjustment^, -IBS, IBB, 1, 13, B) 

self. rateadj , connect ("value_changed", self, rate_adjusted_cb) 

ratebar = gtk. HScale(self . rateadj ) 

ratebar , set_draw_value(False) 

ratebar , set_update_policy (gtk. UPDATE_DISC0NnNU0US ) 



453 453 def pitch_adjusted_cb(self , get]: 

454 454 speech, pitch = int (get, value) 

455 455 speech, say(_("pitch adjusted")) 

455 f = open (os, path, join (self .activity, get_activity_root(), 



'insta 



If there are two people working on the same program independently a version control 
system will merge their changes together automatically. 

Suppose you're working on a major new version of your Activity when someone finds a 
really embarrassing bug in the version you just released. If you use Git you don't need 
to tell people to live with it until the next release, which could be months away. Instead 
you can create a branch of the previous version and work on it alongside the version 
you're enhancing. In effect Git treats the old version you're fixing and the version you're 
improving as two separate projects. 

You can learn more about Git at the Git website: http: //git-scm. com/ . 
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When you're ready for a Git repository for your project you can set one up here: 
http : //git . sugar lab s , or g/ . I will have more to say about setting up and using a Git 
repository later in this book. 

There is a Git repository containing all the code examples from this book. Once you 
have Git installed you can copy the repository to your computer with this command: 

git clone git : //git . sugarlabs . org/\ 

myo- sugar- activities -examples /mainline .git 

This command should be typed all on one line. The backslash (\ ) character at the end 
of the first line is used in Linux to continue a long command to a second line. It is used 
here to make the command fit on the page of the printed version of this book. When 
you type in the command you can leave it out and type myo-sugar-activities- 
examples/mainline.git immediately following git.sugarlabs.org/. 

This convention of splitting long commands over multiple lines will be used throughout 
this book. In addition to that, the code in Git will generally have longer lines than 
you'll see in the code listings in the book. For that reason I'd recommend that you not 
try to type in the code from these listings, but use the code in Git instead. 

The GIMP 

The GIMP is one of the most useful and badly named programs ever developed. You 
can think of it as a free version of Adobe Photoshop. If you need to work with image 
files (other than SVG's) you need this program. 
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You may never need this program to develop the Activity itself, but when it's time to 
distribute the Activity you'll use it to create screen shots of your Activity in action. 
Nothing sells an Activity to a potential user like good screen shots. 



Sugar Emulation 

Most Linux distributions should have Sugar included. In Fedora you can run Sugar as 
an alternative desktop environment. When you log in to GDM Sugar appears as a 
desktop selection alongside GNOME, KDE, Window Maker, and any other window 
managers you have installed. 

This is not the normal way to use Sugar for testing. The normal way uses a tool called 
Xephyr to run a Sugar environment in a window on your desktop. In effect, Xephyr 
runs an X session inside a window and Sugar runs in that. You can easily take screen 
shots of Sugar in action, stop and restart Sugar sessions without restarting the computer, 
and run multiple copies of Sugar to test collaboration. 



I] Applications HaMi Svstsfii ftf,' r} 
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I'll have more to say about this when it's time to test your first Activity. 
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6. 



Creating your First Sugar Activity 



Make A Standalone Python Program First 

The best advice I could give a beginning Activity developer is to make a version of your 
Activity that can run on its own, outside of the Sugar environment. Testing and 
debugging a Python program that stands alone is faster, easier and less tedious than 
doing the same thing with a similar Activity You'll understand why when you start 
testing your first Activity. 

The more bugs you find before you turn your code into an Activity the better. In fact, 
it's a good idea to keep a standalone version of your program around even after you 
have the Activity version well underway. I used my standalone version of Read Etexts 
to develop the text to speech with highlighting feature. This saved me a lot of time, 
which was especially important because I was figuring things out as I went. 

Our first project will be a version of the Read Etexts Activity I wrote. 

Inherit From The sugar.activity .Activity Class 

Next we're going to take our standalone Python program and make an Activity out of 
it. To do this we need to understand the concept of inheritance. In everyday speech 
inheritance means getting something from your parents that you didn't work for. A 
king will take his son to a castle window and say, "Someday, lad, this will all be yours!" 
That's inheritance. 

In the world of computers programs can have parents and inherit things from them. 
Instead of inheriting property, they inherit code. There is a piece of Python code called 
sugar.activity. Activity that's the best parent an Activity could hope to have, and we're 
going to convince it to adopt our program. This doesn't mean that our program will 
never have to work again, but it won't have to work as much. 

Package The Activity 

Now we have to package up our code to make it something that can be run under Sugar 
and distributed as an .xo file. This involves setting up a MANIFEST, activity.info, 
setup.py, and creating a suitable icon with Inkscape. 
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Add Refinements 

Every Activity will have the basic Activity toolbar. For most Activities this will not be 
enough, so we'll need to create some custom toolbars as well. Then we need to hook 
them up to the rest of the Activity code so that what happens to the toolbar triggers 
actions in the Activity and what happens outside the toolbar is reflected in the state of 
the toolbar. 

In addition to toolbars we'll look at some other ways to spiff up your Activity. 

Put The Project Code In Version Control 

By this time we'll have enough code written that it's worth protecting and sharing with 
the world. To do that we need to create a Git repository and add our code to it. We'll 
also go over the basics of using Git. 

Going International With Pootle 

Now that our code is in Git we can request help from our first collaborator: the Pootle 
translation system. With a little setup work we can get volunteers to make translated 
versions of our Activity available. 

Distributing The Activity 

In this task we'll take our Activity and set it up on http: //activities . sugarlab s . org plus 
we'll package up the source code so it can be included in Linux distributions. 

Add Collaboration 

Next we'll add code to share e-books with Friends and the Neighborhood. 

Add Text To Speech 

Text to Speech with word highlighting is next. Our simple project will become a Kindle- 
killer! 



24 



/ • A Standalone Python Program For 
Reading Etexts 

The Program 

Our example program is based on the first Activity I wrote, Read Etexts. This is a 
program for reading free e-books. 

The oldest and best source of free e-books is a website called Project Gutenberg 
(http://www.gutenberg.org/wiki/Main Page ). They create books in plain text format, in 
other words the kind of file you could make if you typed a book into Notepad and hit 
the Enter key at the end of each line. They have thousands of books that are out of 
copyright, including some of the best ever written. Before you read further go to that 
website and pick out a book that interests you. Check out the "Top 100" list to see the 
most popular books and authors. 

The program we're going to create will read books in plain text format only. 

There is a Git repository containing all the code examples in this book. Once you have 
Git installed you can copy the repository to your computer with this command: 

git clone git : //git . sugarlabs . org/\ 

myo- sugar- activities -examples /mainline .git 

The code for our standalone Python program will be found in the directory 
Make_Standalone_Python in a file named ReadEtexts.py. It looks like this: 

# ! /usr/bin/env python 
import sys 
import os 
import zipfile 
import pygtk 
import gtk 
import getopt 
import pango 

page=0 
PAGE_SIZE =45 

class ReadEtexts ( ) : 

def keypress_cb ( self , widget, event): 

"Respond when the user presses one of the arrow keys" 
keyname = gtk . gdk . keyval_name (event . keyval ) 
if keyname == 'plus' : 

self . f ont_increase ( ) 
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return True 
if keyname == 'minus' : 

self . font_de crease ( ) 

return True 
if keyname == ' Page_Up ' : 

self . page_previous () 

return True 
if keyname == ' Page_Down ' : 

self . page_next () 

return True 
if keyname == 'Up' or keyname == ' KP_Up ' \ 
or keyname == 'KP_Left' : 

self . scrollup ( ) 

return True 
if keyname == 'Down' or keyname == ' KP_Down ' \ 
or keyname == ' KP_Right ' : 

self . scroll_down ( ) 

return True 
return False 

def page_previous (self ) : 
global page 
page=page-l 
if page < 0: page=0 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . upper - \ 
v_adj ustment .page_size 

def page_next ( self ) : 
global page 
page=page+l 

if page >!= len (self .page_index) : page=0 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . lower 

def f ont_decrease (self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size - 1 
if font_size < 1: 
font_size = 1 
self . f ont_desc . set_size ( f ont_size * 1024) 
self.textview . modif y_f ont (self . f ont_desc) 

def f ont_increase (self ) : 

font^size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size + 1 

self . f ont_desc . set_size ( f ont_size * 1024) 
self.textview .modif y_f ont (self . f ont_desc) 

def scroll_down (self ) : 
v_adjustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . upper - \ 
v adjustment .page size: 
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self . page_next ( ) 

return 
if v_adj ustment . value < v_adjustment . upper -\ 

v_adj ustment .page_size: 

new_value = v_adjustment . value + \ 
v_adj ustment . step_increment 

if new value > v adjustment . upper -\ 
v_adj ustment .page_size: 
new value = v adjustment . upper -\ 
v_adj ustment .page_size 

v adj ustment . value = new value 

def scroll_up ( self ) : 
v_adjustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . lower : 
self . page_previous () 
return 
if v_adj ustment . value > v_adjustment . lower : 
new value = v adjustment . value - \ 

v_adj ustment . step_increment 
if new_value < v_adjustment . lower : 
new_value = v_adjustment . lower 
v adj ustment . value = new value 

def show_page ( self , page_number) : 

global PAGE_SIZE, current_word 

position = self . page_index [pagenumber ] 

self . etext_f ile . seek (position) 

linecount = 

label_text = '\n\n\n' 

textbuffer = self . textview . get_buf f er ( ) 

while linecount < PAGE_SIZE: 

line = self . etext_f ile . readline ( ) 
label_text = label_text + Unicode (line, 

'iso-8859-1' ) 
linecount = linecount + 1 

label_text = label_text + '\n\n\n' 

textbuffer. set_text (label_text ) 

self. textview. set_buf f er (textbuffer) 

def save_extracted_f ile (self , zipfile, filename) : 

"Extract the file to a temp directory for viewing' 
filebytes = zipfile . read ( filename) 
f = open("/tmp/" + filename, 'w') 
try : 

f. write (filebytes) 
finally: 

f . close 

def read_f ile ( self , filename) : 
"Read the Etext file" 
global PAGE_SIZE 

if zipfile . is_zipf ile ( filename) : 

self.zf = zipfile . ZipFile ( filename, 'r') 
self . book_f iles = self . zf . namelist ( ) 
self. save extracted file (self . zf, 
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self .book_files [0] ) 
currentFileName = "/tmp/" + self . book_f iles [ J 
else : 

currentFileName = filename 

self . etext_f ile = open (currentFileName, "r" ) 

self . page_index = [ ] 

linecount = 

while self . etext_f ile : 

line = self . etext_f ile . readline ( ) 
if not line : 

break 
linecount = linecount + 1 
if linecount >= PAGE_SIZE: 

position = self . etext_f ile . tell ( ) 
self.page_index. append (position) 
linecount = 
if filename.endswithC.zip") : 
os . remove (currentFileName) 

def destroy_cb (self , widget, data=None): 
gtk .main_quit () 

def main (self, file_path) : 

self. window = gtk .Window (gtk . WINDOW_TOPLEVEL) 

self. window. connect ("destroy", self. destroy_cb) 

self. window. set_title ( "Read E texts" ) 

self . window . set_size_re quest ( 640 , 480) 

self. window. set_border_width (0 ) 

self . read_f ile ( f ile_path) 

self . scrolled_window = gtk . ScrolledWindow ( 

hadjustment=None, vadjustment=None) 
self . textview = gtk . TextView ( ) 
self.textview. set_edi table (False) 
self. textview. set_lef t_margin (50 ) 
self. textview. set_cursor_visible (False) 
self. textview. connect ( "key_press_event" , 

self . keypress_cb) 
buffer = self . textview . get_buffer ( ) 
self . f ont_desc = pango . FontDescription ( "sans 12") 
font_size = self . f ont_desc . get_size ( ) 
self. textview . modif y_f ont (self . f ont_desc) 
self . show_page ( ) 

self . scrolled_window . add (self. textview) 
self. window. add (self . scrolled_window) 
self. textview. show() 
self . scrolled_window . show ( ) 
v_adjustment = \ 

self . scrolled_window . get_vadjustment ( ) 
self.window.show() 
gtk .main ( ) 

if name == " main " : 

try: 

opts, args = getopt . getopt (sys . argv [ 1 : ] , "") 

ReadE texts () .main (args [0] ) 
except getopt . error , msg: 

print msg 
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print "This program has no options" 
sys . exit (2 ) 



Running The Program 



To run the program you should first make it executable. You only need to do this once: 

chmod 755 ReadEtexts . py 

For this example I downloaded the file for Pride and Prejudice. The program will work 
with either of the Plain text formats, which are either uncompressed text or a Zip file. 
The zip file is named 1342.zip, and we can read the book by running this from a 
terminal: 

. /ReadEtexts . py 1342.zip 

This is what the program looks like in action: 



Read Etexts 



Produced by Anonymous Volunteers 



PRIDEAND PREJUDICE 
By Jane Austen 

Chapter 1 



It is a truth universally acknowledged, that a single man in possession 
of a good fortune, must be in want of a wife, 

However little known the feelings or views of such a man may be on his 
first entering a neighbourhood, this truth is so well fixed in the minds 



u. 



_ 



You can use the Page Up, Page Down, Up, Down, Left, and Right keys to navigate 
through the book and the '+' and '-' keys to adjust the font size. 
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How The Program Works 

This program reads through the text file containing the book and divides it into pages of 
45 lines each. We need to do this because the gtk.TextView component we use for 
viewing the text would need a lot of memory to scroll through the whole book and that 
would hurt performance. A second reason is that we want to make reading the e-book 
as much as possible like reading a regular book, and regular books have pages. If a 
teacher assigns reading from a book she might say "read pages 35-50 for tommorow". 
Finally, we want this program to remember what page you stopped reading on and 
bring you back to that page again when you read the book next time. (The program we 
have so far doesn't do that yet). 

To page through the book we use random access to read the file. To understand what 
random access means to a file, consider a VHS tape and a DVD. To get to a certain 
scene in a VHS tape you need to go through all the scenes that came before it, in order. 
Even though you do it at high speed you still have to look at all of them to find the 
place you want to start watching. This is sequential access. On the other hand a DVD 
has chapter stops and possibly a chapter menu. Using a chapter menu you can look at 
any scene in the movie right away, and you can skip around as you like. This is 
random access, and the chapter menu is like an index. Of course you can access the 
material in a DVD sequentially too. 

We need random access to skip to whatever page we like, and we need an index so that 
we know where each page begins. We make the index by reading the entire file one line 
at a time. Every 45 lines we make a note of how many characters into the file we've 
gotten and store this information in a Python list. Then we go back to the beginning of 
the file and display the first page. When the program user goes to the next or previous 
page we figure out what the new page number will be and look in the list entry for that 
page. This tells us that page starts 4,200 characters into the file. We use seek() on the 
file to go to that character and then we read 45 lines starting at that point and load them 
into the TextView. 

When you run this program notice how fast it is. Python programs take longer to run a 
line of code than a compiled language would, but in this program it doesn't matter 
because the heavy lifting in the program is done by the TextView, which was created in 
a compiled language. The Python parts don't do that much so the program doesn't 
spend much time running them. 

Sugar uses Python a lot, not just for Activities but for the Sugar environment itself. You 
may read somewhere that using so much Python is "a disaster" for performance. Don't 
believe it. 
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There are no slow programming languages, only slow programmers. 
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O • Inherit From sugar .activity .Activity 

Object Oriented Python 

Python supports two styles of programming: procedural and object oriented. 
Procedural programming is when you have some input data, do some processing on it, 
and produce an output. If you want to calculate all the prime numbers under a hundred 
or convert a Word document into a plain text file you'll probably use the procedural 
style to do that. 

Object oriented programs are built up from units called objects. An object is described 
as a collection of fields or attributes containing data along with methods for doing things 
with that data. In addition to doing work and storing data objects can send messages to 
one another. 

Consider a word processing program. It doesn't have just one input, some process, and 
one output. It can receive input from the keyboard, from the mouse buttons, from the 
mouse traveling over something, from the clipboard, etc. It can send output to the 
screen, to a file, to a printer, to the clipboard, etc. A word processor can edit several 
documents at the same time too. Any program with a GUI is a natural fit for the object 
oriented style of programming. 

Objects are described by classes. When you create an object you are creating an instance 
of a class. 

There's one other thing that a class can do, which is to inherit methods and attributes 
from another class. When you define a class you can say it extends some class, and by 
doing that in effect your class has the functionality of the other class plus its own 
functionality. The extended class becomes its parent. 

All Sugar Activities extend a Python class called sugar.activity.Activity. This class 
provides methods that all Activities need. In addition to that, there are methods that 
you can override in your own class that the parent class will call when it needs to. For 
the beginning Activity writer three methods are important: 

init () 

This is called when your Activity is started up. This is where you will set up the user 
interface for your Activity, including toolbars. 
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rea d_file(self, filejpa th ) 

This is called when you resume an Activity from a Journal entry. It is called after the 

init () method is called. The file_path parameter contains the name of a temporary 

file that is a copy of the file in the Journal entry. The file is deleted as soon as this 
method finishes, but because Sugar runs on Linux if you open the file for reading your 
program can continue to read it even after it is deleted and it the file will not actually go 
away until you close it. 

write_file(self, filejpa th ) 

This is called when the Activity updates the Journal entry. Just like with read_file() your 
Activity does not work with the Journal directly Instead it opens the file named in 
file_path for output and writes to it. That file in turn is copied to the Journal entry. 

There are three things that can cause write_file() to be executed: 

• Your Activity closes. 

• Someone presses the Keep button in the Activity toolbar. 

• Your Activity ceases to be the active Activity, or someone moves from the Activity 
View to some other View. 

In addition to updating the file in the Journal entry the read_file() and write_file() 
methods are used to read and update the metadata in the Journal entry. 

When we convert our standalone Python program to an Activity we'll take out much of 
the code we wrote and replace it with code inherited from the sugar.activity.Activity 
class. 



Extending The Activity Class 



Here's a version of our program that extends Activity. You'll find it in the Git repository 
in the directory Inherit_From_sugar.activity.Activity under the name 
ReadEtextsActivity.py: 



import sys 

import os 

import zipfile 

import pygtk 

import gtk 

import pango 

from sugar . activity import activity 

from sugar . graphics import style 



33 



page=0 
PAGE_SIZE =45 

class ReadEtextsActivity (activity .Activity) : 

def init (self, handle) : 

"The entry point to the Activity" 

global page 

activity. Activity . init (self, handle) 

toolbox = activity . ActivityToolbox (self ) 
activity_toolbar = toolbox . get_activity_toolbar ( ) 
activity_toolbar . keep .props .visible = False 
activity_toolbar . share .props .visible = False 
self . set_toolbox (toolbox) 

toolbox . show ( ) 

self . scrolled_window = gtk . ScrolledWindow ( ) 

self. scrolled_window. set_policy (gtk. POLICY_NEVER, 

gtk. POLICY_AUTOMATIC) 
self . scrolled_window .props . shadow_type = \ 

gtk.SHADOW_NONE 

self . textview = gtk . TextView ( ) 
self .textview. set_edi table (False) 
self. textview. set_cursor_visible (False) 
self. textview. set_lef t_margin (50 ) 
self. textview. connect ( "key_press_event" , 
self . keypress_cb) 

self . scrolled_window . add (self. textview) 

self . set_canvas (self . scrolled_window) 

self. textview. show() 

self . scrolled_window . show ( ) 

page = 

self . textview . grab_focus () 

self . f ont_desc = pango . FontDescription ( "sans %d" % 

style . zoom ( 10 ) ) 
self. textview . modif y_f ont (self . f ont_desc) 

def keypress_cb (self , widget, event): 

"Respond when the user presses one of the arrow keys" 

keyname = gtk . gdk . keyval_name (event . keyval) 

print keyname 

if keyname == 'plus': 

self . f ont_increase ( ) 

return True 
if keyname == 'minus' : 

self . font_de crease ( ) 

return True 
if keyname == ' Page_Up ' : 

self . page_previous () 

return True 
if keyname == 'PageDown' : 

self . page_next () 

return True 
if keyname == 'Up' or keyname == ' KP_Up ' \ 
or keyname == 'KP_Left' : 

self . scrollup ( ) 
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return True 
if keyname == 'Down' or keyname == ' KP_Down ' \ 
or keyname == 'KP_Right' : 

self . scroll_down ( ) 

return True 
return False 

def page_previous ( self ) : 
global page 
page=page-l 
if page < 0: page=0 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadjustment ( ) 
v_adj ustment . value = v_adjustment . upper -\ 
v_adj ustment .page_size 

def page_next ( self ) : 
global page 
page=page+l 

if page >= len ( self .page_index) : page=0 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . lower 

def f ont_decrease ( self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size - 1 
if font_size < 1: 
font_size = 1 
self . f ont_desc . set_size ( f ont_size * 1024) 
self.textview . modif y_f ont (self . f ont_desc) 

def f ont_increase ( self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size + 1 

self . f ont_desc . set_size ( f ontsize * 1024) 
self.textview .modif y_f ont (self . f ont_desc) 

def scrolldown ( self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . upper - \ 
v_adj ustment .page_size: 
self . page_next ( ) 
return 
if v_adj ustment . value < v_adjustment . upper -\ 
v_adj ustment .page_size: 
new_value = v_adjustment . value +\ 

v_adj ustment . step_increment 
if new_value > v_adjustment . upper -\ 
v_adj ustment .page_size: 
new value = v adjustment . upper -\ 
v_adj ustment .page_size 
v adj ustment . value = new value 

def scroll_up ( self ) : 
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v_adjustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . lower : 

self . page_previous () 

return 
if v_adj ustment . value > v_adjustment . lower : 

new value = v adjustment .value - \ 
v_adjustment . step_increment 

if new_value < v_adjustment . lower : 
new value = v adjustment . lower 

v adj ustment . value = new value 

def show_page ( self , page_number) : 

global PAGE_SIZE, current_word 

position = self .page_index [page_number ] 

self . etext_f ile .seek (position) 

linecount = 

label_text = '\n\n\n' 

textbuffer = self . textview . get_buffer ( ) 

while linecount < PAGE_SIZE: 

line = self . etext_f ile . readline ( ) 
label_text = label_text + Unicode (line, 

'iso-8859-1' ) 
linecount = linecount + 1 

label_text = label_text + '\n\n\n' 

textbuffer. set_text (label_text ) 

self. textview. setbuffer (textbuffer) 

def save_extracted_f ile (self , zipfile, filename): 

"Extract the file to a temp directory for viewing' 
filebytes = zipfile . read ( filename) 
outfn = self .make_new_f ilename (filename) 
if (outfn == ' ' ) : 

return False 
f = open (os .path . j oin (self . get_activity_root () , 

'instance', outfn), 'w') 
try: 

f. write (filebytes) 
finally: 

f . close 

def read_f ile ( self , filename) : 
"Read the Etext file" 
global PAGE_SIZE 

if zipfile . is_zipf ile ( filename) : 

self.zf = zipfile . ZipFile (filename, 'r') 
self . book_f iles = self . zf . namelist ( ) 
self . save_ext r act ed_ file (self . zf , 

self .book_filesT0] ) 
currentFileName = os .path . j oin ( 
self . get_activity_root () , 
'instance', self .book_f iles [ ] ) 
else : 

currentFileName = filename 

self . etext_f ile = open (currentFileName, "r" ) 
self . page_index = [ ] 
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linecount = 

while self . etext_f ile : 

line = self . etext_f ile . readline ( ) 
if not line: 

break 
linecount = linecount + 1 
if linecount >= PAGE_SIZE: 

position = self . etext_f ile . tell ( ) 
self . page_index . append (position) 
linecount = 
if filename.endswithC.zip") : 

os . remove (currentFileName) 
self . show_page ( ) 

def make_new_f ilename ( self , filename) : 

partition_tuple = f ilename . rpartition ('/' ) 
return partition tuple [2] 



This program has some significant differences from the standalone version. First, note 
that this line: 

# ! /usr/bin/env python 

has been removed. We are no longer running the program directly from the Python 
interpreter. Now Sugar is running it as an Activity. Notice that much (but not all) of 

what was in the main() method has been moved to the init () method and the 

mainO method has been removed. 

Notice too that the class statement has changed: 

class Re a dEtextsActivity (activity. Activity) 

This statement now tells us that class ReadEtextsActivity extends the class 
sugar.activity.Activity. As a result it inherits the code that is in that class. Therefore 
we no longer need a GTK main loop, or to define a window. The code in this class we 
extend will do that for us. 

While we gain much from this inheritance, we lose something too: a title bar for the 
main window. In a graphical operating environment a piece of software called a window 
manager is responsible for putting borders on windows, making them resizeable, 
reducing them to icons, maximizing them, etc. Sugar uses a window manager named 
Matchbox which makes each window fill the whole screen and puts no border, title bar, 
or any other window decorations on the windows. As a result of that we can't close our 
application by clicking on the "X" in the title bar as before. To make up for this we need 
to have a toolbar that contains a dose button. Thus every Activity has an Activity 
toolbar that contains some standard controls and buttons. If you look at the code you'll 
see I'm hiding a couple of controls which we have no use for yet. 
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The read_file() method is no longer called from the main() method and doesn't seem to 
be called from anywhere in the program. Of course it does get called, by some of the 

Activity code we inherited from our new parent class. Similarly the init () and 

write _file() methods (if we had a write_file() method) get called by the parent Activity 
class. 

If you're especially observant you might have noticed another change. Our original 
standalone program created a temporary file when it needed to extract something from 
a Zip file. It put that file in a directory called /tmp. Our new Activity still creates the file 
but puts it in a different directory, one specific to the Activity. 

All writing to the file system is restricted to subdirectories of the path given by 
self.get_activity _root(). This method will give you a directory that belongs to your 
Activity alone. It will contain three subdirectories with different policies: 

data 

This directory is used for data such as configuration files. Files stored here will 
survive reboots and OS upgrades. 

tmp 

This directory is used similar to the /tmp directory, being backed by RAM. It may 
be as small as 1 MB. This directory is deleted when the activity exits. 

instance 

This directory is similar to the tmp directory, being backed by the computer's drive 
rather than by RAM. It is unique per instance. It is used for transfer to and from 
the Journal. This directory is deleted when the activity exits. 

Making these changes to the code is not enough to make our program an Activity. We 
have to do some packaging work and get it set up to run from the Sugar emulator. We 
also need to learn how to run the Sugar emulator. That comes next! 
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Zs • Package The Activity 



Add setup.py 

You'll need to add a Python program called setup.py to the same directory that you 
Activity program is in. Every setup.py is exactly the same as every other setup.py. 
The copies in our Git repository look like this: 

# ! /usr/bin/env python 

# Copyright (C) 2006, Red Hat, Inc. 
# 

# This program is free software; you can redistribute it 

# and/or modify it under the terms of the GNU General 

# Public License as published by the Free Software 

# Foundation; either version 2 of the License, or (at 

# your option) any later version. 
# 

# This program is distributed in the hope that it will 

# be useful, but WITHOUT ANY WARRANTY; without even 

# the implied warranty of MERCHANTABILITY or FITNESS 

# FOR A PARTICULAR PURPOSE. See the GNU General 

# Public License for more details. 
# 

# You should have received a copy of the GNU General 

# Public License along with this program; if not, 

# write to the Free Software Foundation, Inc., 

# 51 Franklin St, Fifth Floor, Boston, MA 

# 02110-1301 USA 

from sugar . activity import bundlebuilder 
bundlebuilder . start ( ) 

Be sure and copy the entire text above, including the comments. 

The setup.py program is used by sugar for a number of purposes. If you run setup.py 
from the command line you'll see the options that are used with it and what they do. 

[jim@simmons bookexamples ] $ ./setup.py 
/usr/lib/python2 .6/site-packages/sugar/util.py:25: 
DeprecationWarning : the sha module is deprecated; 
use the hashlib module instead 

import sha 
Available commands: 

build Build generated files 

dev Setup for development 

dist_xo Create a xo bundle package 

dist_source Create a tar source package 

fix manifest Add missing files to the manifest 
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genpot Generate the gettext pot file 

install Install the activity in the system 

(Type ". /setup. py <command> --help" for help about a 
particular command's options. 

We'll be running some of these commands later on. Don't be concerned about the 
DeprecationWarning message. That is just Python's way of telling us that it has a 
new way of doing something that is better but the old way we are using still works. 
The error is coming from code in Sugar itself and should be fixed in some future Sugar 
release. 

Create activity.info 

Next create a directory within the one your progam is in and name it activity. Create a 
file named activity.info within that directory and enter the lines below into it. Here is 
the one for our first Activity: 

[Activity] 

name = Read ETexts II 

service_name = net . f lossmanuals . ReadEtextsActivity 

icon = read-etexts 

exec = sugar-activity ReadEtextsActivity . ReadEtextsActivity 

show_launcher = no 

activity version = 1 

mime_types = text/plain; application/zip 

license = GPLv2+ 

This file tells Sugar how to run your Activity. The properties needed in this file are: 

name The name of your Activity as it will appear to the user. 

A unique name that Sugar will use to refer to your Activity. Any Journal entry created 
service_name by your Activity will have this name stored in its metadata, so that when someone 
resumes the Journal entry Sugar knows to use the program that created it to read it. 

icon The name of the icon file you have created for the Activity. Since icons are always .svg 

files the icon file in the example is named read-etexts.svg. 

exec This tells Sugar how to launch your Activity. What it says is to create an instance of the 

class ReadEtextsActivity which it will find in file ReadEtextsActivity.py. 

show_launcher There are two ways to launch an Activity. The first is to click on the icon in the Activity 
view. The second is to resume an entry in the Journal. Activities that don't create Journal 
entries can only be resumed from the Journal, so there is no point in putting an icon in 
the Activity ring for them. Read Etexts is an Activity like that. 

activity_version An integer that represents the version number of your program. The first version is 1, 
the next is 2, and so on. 

mime_types Generally when you resume a Journal entry it launches the Activity that created it. In 
the case of an e-book it wasn't created by any Activity, so we need another way to tell 
the Journal which Activity it can use. A MIME type is the name of a common file 
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format. Some examples are text/plain, text/html, application/zip and application/pdf. 
In this entry we're telling the Journal that our program can handle either plain text files 
or Zip archive files. 

license Owning a computer program is not like buying a car. With a car, you're the owner and 

you can do what you like with it. You can sell it, rent it out, make it into a hot rod, 
whatever. With a computer program there is always a license that tells the person 
receiving the program what he is allowed to do with it. GPLv2+ is a popular standard 
license that can be used for Activities, and since this is my program that is what goes 
here. When you're ready to distribute one of your Activities I'll have more to say about 
licenses. 

Create An Icon 

Next we need to create an icon named read-etexts.svg and put it in the activity 
subdirectory. ! We're going to use Inkscape to create the icon. From the New menu in 
Inkscape select icon 48x48. This will create a drawing area that is a good size. 

You don't need to be an expert in Inkscape to create an icon. In fact the less fancy your 
icon is the better. When drawing your icon remember the following points: 

• Your icon needs to look good in sizes ranging from really, really small to large. 

• It needs to be recognizeable when its really, really small. 

• You only get to use two colors: a stroke color and a fill color. It doesn't matter 
which ones you choose because Sugar will need to override your choices anyway, 
so just use black strokes on a white background. 

• A fill color is only applied to an area that is contained within an unbroken stroke. 
If you draw a box and one of the corners doesn't quite connect the area inside that 
box will not be filled. Free hand drawing is only for the talented. Circles, boxes, 
and arcs are easy to draw with Inkscape so use them when you can. 

• Inkscape will also draw 3D boxes using two point perspective. Don't use them. 
Icons should be flat images. 3D just doesn't look good in an icon. 

• Coming up with good ideas for icons is tough. I once came up with a rather nice 
picture of a library card catalog drawer for Get Internet Archive Books. The 
problem is, no child under the age of forty has ever seen a card catalog and fewer 
still understand its purpose. 

When you're done making your icon you need to modify it so it can work with Sugar. 
Specifically, you need to make it show Sugar can use its own choice of stroke color and 
fill color. The SVG file format is based on XML, which means it is a text file with some 
special tags in it. This means that once we have finished editing it in Inkscape we can 
load the file into Eric and edit it as a text file. 
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I'm not going to put the entire file in this chapter because most of it you'll just leave 
alone. The first part you need to modify is at the very beginning. 

Before: 

<?xml version="l . " encoding="UTF-8" standalone="no" ?> 
<!-- Created with Inkscape (http://www.inkscape.org/) --> 
<svg 

After: 

<?xml version="l . 0" ?> 

<!D0CTYPE svg PUBLIC '-//W3C//DTD SVG 1.1//EN' 

'http: // www. w3.org/ Graphics/ SVG/ 1 . 1/ DTD /svg 11 . dtd' [ 

<!ENTITY stroke_color "#000000"> 

<!ENTITY fill_color "#FFFFFF"> 
] Xsvg 

Now in the body of the document you'll find references to fill and stroke as part of an 
attribute called style. Every line or shape you draw will have these, like this: 

<rect 

style="fill:#ffffff;stroke:#000000; stroke-opacity: 1" 

id="rect904" 

width="36. 142857" 

height="32 . 142857" 

x="4 . 1428571" 

y="7 . 1428571" /> 

You need to change each one to look like this: 

<rect 

style="fill:&fill_color;; stroke: &stroke_color ; 
; stroke-opacity: 1 " 

id="rect904" 

width="36. 142857" 

height="32 . 142857" 

x="4 . 1428571" 

y="7 . 1428571" /> 

Note that & 'stroke _color; and &fill_color; both end with semicolons (;), and semicolons are 
also used to separate the properties for style. Because of this it is an extremely common 
beginner's mistake to leave off the trailing semicolon because two semicolons in a row 
don't look right. Be assured that the two semicolons in a row are intentional and 
absolutely necessary! Second, the value for style should all go on one line. We split it 
here to make it fit on the printed page; do not split it in your own icon! 

Make a MANIFEST File 

You should remember that setup.py has an option to update a manifest. Let's try it: 
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. /setup. py f ix_manif est 

/usr/lib/python2 .6/site-packages/sugar/util.py:25: 
DeprecationWarning : the sha module is deprecated; 
use the hashlib module instead 

import sha 
WARNING : root :Missing po/ dir, cannot build_locale 
WARNING: root :Activity directory lacks a MANIFEST file. 

This actually will build a MANIFEST file containing everything in the directory and its 
subdirectories. The /po directory it is complaining about is used to translate Activities 
into different languages. We can ignore that for now. 

The MANIFEST file it creates will contain some extra stuff, so we need to get rid of the 
extra lines using Eric. The corrected MANIFEST should look like this: 

setup . py 

Re adE texts Activity . py 
activity/read- etexts.svg 
activity/ activity. info 

Install The Activity 

There's just one more thing to do before we can test our Activity under the Sugar 
emulator. We need to install it, which in this case means making a symbolic link 
between the directory we're using for our code in the -/Activities/ directory. The 
symbol ~ refers to the "home" directory of the user we're running Sugar under, and a 
symbolic link is a way to make a file or directory appear to be located in more than one 
place without copying it. We make this symbolic link by running setup. py again: 

. /setup . py dev 

Running Our Activity 

Now at last we can run our Activity under Sugar. To do that we need to learn how to 
run sugar-emulator. 

Fedora doesn't make a menu option for Sugar Emulator, but it's easy to add one 
yourself. The command to run is simply 

sugar-emulator 

If your screen resolution is smaller than the default size sugar-emulator runs at it will 
run full screen. This is not convenient for testing, so you may want to specify your own 
size: 

sugar-emulator -i 800x600 
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Note that this option only exists in Fedora 11 and later. 

When you run sugar-emulator a window opens up and the Sugar environment starts up 
and runs inside it. It looks like this: 
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When running sugar-emulator you may find that some keys don't seem to work in the 
Sugar environment. This is caused by bugs in the Xephyr software that creates the 
window that Sugar runs in. Sometimes it has difficulty identifying your keyboard and 
as a result some keys get misinterpreted. On Fedora 111 noticed that my function keys 
did not work, and my regular arrow keys didn't work either although my keypad arrow 
keys did. I was able to get my function keys working again by putting this line in 
~ I. sugar I debug: 

run setxkbmap <keymap name> 

This needs more explanation. First, the symbol "~" refers to your home directory. 
Second, any file named starting with a period is considered hidden in Linux, so you'll 
need to use the option to show hidden files and directories in the GNOME directory 
browser to navigate to it. Finally, the keymap name is a two character country code: us 
for the United States, fr for France, de for Germany, etc. 
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To test our Activity we're going to need to have a book in the Journal, so use the 
Browse Activity to visit Project Gutenberg again and download the book of your 
choice. This time it's important to download the book in Zip format, because Browse 
cannot download a plain text file to the Journal. Instead, it opens the file for viewing as 
if it was a web page. If you try the same thing with the Zip file it will create an entry in 
the Journal. 

We can't just open the file with one click in the Journal because our program did not 
create the Journal entry and there are several Activities that support the MIME type of 
the Journal entry. We need to use the Start With menu option like this: 




When we do open the Journal entry this is what we see: 
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Produced by Anonymous Volunteers 



PRIDE AND PREJUDICE 
By Jane Austen 



Chapter 1 



It is a truth universally acknowledged, that a single man in possession 
of a good fortune, must be in want of a wife. 

However little known the feelings or views of such a man may be on his 
first entering a neighbourhood, this truth is so well fixed in the minds 



Technically, this is the first iteration of our Activity. (Iteration is a vastly useful word 
meaning something you do more than once. In this book we're building our Activity a 
bit at a time so I can demonstrate Activity writing principles, but actually building a 
program in pieces, testing it, getting feedback, and building a bit more can be a highly 
productive way of creating software. Using the word iteration to describe each step in 
the process makes the process sound more formal than it really is). 

While this Activity might be good enough to show your own mother, we really should 
improve it a bit before we do that. That part comes next. 
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-L U • Add Refinements 



Toolbars 

It is a truth universally acknowledged that a first rate Activity needs good Toolbars. In 
this chapter we'll learn how to make them. We're going to put the toolbar classes in a 
separate file from the rest, because there are two styles of toolbar (old and new) and we 
may want to support both in our Activity. If we have two different files containing 
toolbar classes our code can decide at runtime which one it wants to use. For now, this 
code supports the old style, which works with every version of Sugar. The new style is 
currently only supported by Sugar on a Stick. 

There is a file called toolbar.py in the Add_Refinements directory of the Git 
repository that looks like this: 

from gettext import gettext as 
import re 

import pango 
import gobject 
import gtk 

from sugar . graphics . toolbutton import ToolButton 
from sugar . activity import activity 

class ReadToolbar (gtk . Toolbar ) : 

gtype_name = 'ReadToolbar' 

def init (self): 

gtk. Toolbar . init (self) 

self. back = ToolButton (' go-previous ' ) 
self. back. set_tooltip (_ ( ' Back ' ) ) 
self . back . props . sensitive = False 
self . insert ( self . back, -1) 
self. back. show ( ) 

self. forward = ToolButton (' go-next ' ) 
self. forward. set_tooltip (_( 'Forward')) 
self . forward. props . sensitive = False 
self . insert ( self . forward, -1) 
self. forward. show () 

num_page_item = gtk . Toolltem ( ) 

self . num_page_entry = gtk. Entry () 

self . num_page_entry . set_text ( ' ' ) 

self . num_page_entry . set_alignment ( 1 ) 

self . num_page_entry .connect ( 'insert-text' , 
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self . num_page_entry_insert_text_cb) 

self . num_page_entry . set_width_chars (4 ) 

num_page_item. add (self . num_page_entry) 
self . num_page_entry . show ( ) 

self . insert (num_page_item, -1) 
num_page_item. show ( ) 

total_page_item = gtk . Toolltem ( ) 

self . total_page_label = gtk. Label () 

label_attributes = pango . AttrList ( ) 
label_attributes .insert (pango . AttrSize ( 

14000, 0, -1)) 
label_attributes .insert (pango. At tr Fore ground ( 

65535, 65535, 65535, 0, -1)) 
self . total_page_label . set_at tributes ( 

label_at tributes ) 

self . total_page_label . set_text ( ' / 0') 
total_page_item. add (self . total_page_label ) 
self . total_page_label . show ( ) 

self . insert (total_page_item, -1) 
total_page_item. show ( ) 

def num_page_entry_insert_text_cb (self , entry, text, 
length, position) : 
if not re. match (' [0-9] ' , text): 

entry. emit_stop_by_name ('insert-text') 
return True 
return False 

def update_nav_buttons (self ) : 

current page = self. current page 

self . back . props . sensitive = current_page > 

self . forward. props . sensitive = \ 

current_page < self . total_pages - 1 

self . num_page_entry .props . text = str ( 

current_page + 1) 
self . total_page_label .props . label = \ 

' / ' + str (self . total_pages ) 

def set_total_pages (self , pages): 
self . total_pages = pages 

def set_current_page (self , page): 
self . current_page = page 
self . update_nav_buttons ( ) 

class ViewToolbar (gtk . Toolbar ) : 

gtype_name = 'ViewToolbar' 

gsignals = { 

48 



'needs-update-size ' : (gob j ect . SIGNAL_RUN_FIRST, 

gobject .TYPE_NONE, 
([])), 
'go-fullscreen' : (gob j ect . SIGNAL_RUN_FIRST, 
gobject .TYPE_NONE, 
( [] ) ) 



} 



def init (self): 

gtk. Toolbar . init (self) 

self . zoom_out = ToolButton (' zoom-out ' ) 
self . zoom_out . set_tooltip (_ ( ' Zoom out ' ) ) 
self . insert ( self . zoom_out, -1) 
self . zoom_out . show ( ) 

self .zoora_in = ToolButton (' zoom-in ' ) 
self . zoom_in . set_tooltip (_ ( ' Zoom in ' ) ) 
self . insert ( self . zoom_in, -1) 
self . zoom_in . show ( ) 

spacer = gtk . SeparatorToolItem ( ) 
spacer . props . draw = False 
self . insert ( spacer , -1) 
spacer . show ( ) 

self . fullscreen = ToolButton (' view-fullscreen ' ) 
self. fullscreen. set_tooltip (_( 'Fullscreen' ) ) 
self. fullscreen. connect ( 'clicked' , 

self . f ullscreen_cb) 
self . insert ( self . fullscreen, -1) 
self. fullscreen. show () 

def f ullscreen_cb ( self , button): 
self . emit ( 'go-fullscreen' ) 

Another file in the same directory of the Git repository is named 
ReadEtextsActivity2.py. It looks like this: 

import os 

import zipfile 

import gtk 

import pango 

from sugar . activity import activity 

from sugar . graphics import style 

from toolbar import ReadToolbar, ViewToolbar 

from gettext import gettext as _ 

page=0 

PAGE_SIZE =45 
TOOLBAR_READ = 2 

class ReadEtextsActivity (activity .Activity) : 

def init (self, handle) : 

"The entry point to the Activity" 

global page 

activity .Activity . init (self, handle) 

toolbox = activity . ActivityToolbox (self ) 
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activity_toolbar = toolbox . get_activity_toolbar ( ) 
activity_toolbar . keep .props .visible = False 
activity_toolbar . share .props .visible = False 

self . edit_toolbar = activity . EditToolbar ( ) 
self . edit_toolbar . undo .props . visible = False 
self . edit_toolbar . redo .props . visible = False 
self . edit_toolbar . separator .props . visible = False 
self . edit_toolbar . copy . set_sensitive (False) 
self . edit_toolbar .copy. connect ( 'clicked' , 

self . edit_toolbar_copy_cb) 
self . edit_toolbar .paste .props . visible = False 
toolbox . add_toolbar (_ ( ' Edit ' ) , self. edit_toolbar ) 
self . edit_toolbar . show ( ) 

self . read_toolbar = ReadToolbar ( ) 

toolbox . add_toolbar (_ ( ' Read 1 ) , self. read_toolbar ) 

self . readtoolbar .back. connect ( 'clicked' , 

self . go_back_cb) 
self . read_toolbar . forward. connect ( 'clicked' , 

self . go_f orward_cb) 
self . read_toolbar . num_page_entry .connect ( 'activate' , 

self . num_page_entry_activate_cb) 
self . read_toolbar . show ( ) 

self . view_toolbar = ViewToolbar ( ) 

toolbox . add_toolbar (_ ( ' View ' ) , self. view_toolbar ) 

self . view_toolbar .connect ( 'go-fullscreen' , 

self . view_toolbar_go_f ullscreen_cb) 
self . view_toolbar . zoom_in .connect ( 'clicked' , 

self . zoom_in_cb) 
self . view_toolbar . zoom_out .connect ( 'clicked' , 

self . zoom_out_cb) 
self . view_toolbar . show ( ) 

self . set_toolbox (toolbox) 

toolbox . show ( ) 

self . scrolled_window = gtk . ScrolledWindow ( ) 

self. scrolled_window. set_policy (gtk. POLICY_NEVER, 

gtk. POLICY_AUTOMATIC) 
self . scrolled_window .props . shadow_type = \ 

gtk.SHADOW_NONE 

self . textview = gtk . TextView ( ) 
self.textview. set_edi table (False) 
self. textview. set_cursor_visible (False) 
self. textview. set_lef t_margin (50 ) 
self. textview. connect ( "key_press_event" , 
self . keypress_cb) 

self . scrolled_window . add (self. textview) 

self . set_canvas (self . scrolled_window) 

self . textview . show ( ) 

self . scrolled_window . show ( ) 

page = 

self . clipboard = gtk . Clipboard ( 

display=gtk . gdk . display_get_def ault () , 

selection=" CLIPBOARD") 



50 



self . textview . grab_f ocus () 

self . f ont_desc = pango . FontDescription ( "sans %d" % 

style . zoom ( 10 ) ) 
self. textview . modif y_f ont (self . f ont_desc) 

buffer = self . textview . get_buffer ( ) 

self .markset_id = buff er . connect ( "mark-set" , 

self . mark_set_cb) 
self. toolbox. set_current_toolbar (TOOLBAR_READ) 

def keypress_cb ( self , widget, event): 

"Respond when the user presses one of the arrow keys" 

keyname = gtk . gdk . keyval_name (event . keyval) 

print keyname 

if keyname == 'plus' : 

self . f ont_increase ( ) 

return True 
if keyname == 'minus' : 

self . f on t_de crease ( ) 

return True 
if keyname == ' Page_Up ' : 

self . page_previous () 

return True 
if keyname == ' Page_Down ' : 

self . page_next ( ) 

return True 
if keyname == 'Up' or keyname == ' KP_Up ' \ 
or keyname == 'KP_Left' : 

self . scroll_up ( ) 

return True 
if keyname == 'Down' or keyname == ' KP_Down ' \ 
or keyname == 'KP_Right' : 

self . scroll_down ( ) 

return True 
return False 

def num_page_entry_activate_cb (self , entry): 
global page 
if entry . props . text : 

new_page = int (entry .props . text ) - 1 
else : 

new_page = 

if new_page >= self . readtoolbar . total_pages : 

new_page = self . readtoolbar . total_pages - 1 

elif new_page < 0: 
new_page = 

self . read_toolbar . current_page = newpage 

self . read_toolbar . set_current_page (new_page) 

self . show_page (new_page) 

entry . props . text = str (newpage + 1) 

self . read_toolbar . update_nav_buttons ( ) 

page = new_page 

def go_back_cb ( self , button) : 
self . page_previous () 
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def go_f orward_cb (self , button): 
self . page_next () 

def page_previous (self ) : 
global page 
page=page-l 
if page < 0: page=0 

self . readtoolbar . set_current_page (page) 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adjustment . value = v_adj ustment . upper -\ 
v_adj ustment .page_size 

def page_next ( self ) : 
global page 
page=page+l 

if page >= len (self .page_index) : page=0 
self . readtoolbar . set_current_page (page) 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . lower 

def zoom_in_cb (self , button) : 
self . f ont_increase ( ) 

def zoom_out_cb (self , button) : 
self . f on t_de crease ( ) 

def f ont_decrease (self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size - 1 
if font_size < 1: 
font_size = 1 
self . f ont_desc . set_size ( f ont_size * 1024) 
self .textview . modif y_f ont (self . f ont_desc) 

def f ont_increase (self ) : 

font^size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size + 1 

self . f ont_desc . set_size ( f ont_size * 1024) 
self. textview .modif y_f ont (self . f ont_desc) 

def mark_set_cb (self , textbuffer, iter, textmark) : 

if textbuf f er . get_has_selection ( ) : 

begin, end = textbuf fer . get_selection_bounds ( ) 
self . edit_toolbar . copy . set_sensitive (True) 

else : 

self . edit_toolbar . copy . set_sensitive (False) 

def edit_toolbar_copy_cb (self , button): 

textbuffer = self . textview . get_buf fer ( ) 
begin, end = textbuf fer . get_selection_bounds ( ) 
copy_text = textbuf fer . get_text (begin, end) 
self. clipboard. set_text (copy_text ) 
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def view_toolbar_go_f ullscreen_cb (self , view_toolbar ) : 
self. fullscreen () 

def scrolldown ( self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . upper - \ 
v_adj ustment .page_size : 
self . page_next ( ) 
return 
if v_adj ustment . value < v_adjustment . upper - \ 
v_adj ustment .page_size: 
new_value = v_adjustment . value + \ 

v_adj ustment . step_increment 
if new_value > v_adjustment . upper - \ 
v_adj ustment .page_size: 
new value = v adjustment . upper - \ 
v_adj ustment .page_size 
v adj ustment . value = new value 

def scroll_up ( self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . lower : 
self . page_previous () 
return 
if v_adj ustment . value > v_adjustment . lower : 
new value = v adjustment . value - \ 

v_adj ustment . step_increment 
if new_value < v_adjustment . lower : 
new_value = v_adjustment . lower 
v adj ustment . value = new value 

def show_page ( self , pagenumber) : 

global PAGE_SIZE, current_word 

position = self . page_index [pagenumber ] 

self . etext_f ile . seek (position) 

linecount = 

label_text = '\n\n\n' 

textbuffer = self . textview . get_buf f er ( ) 

while linecount < PAGE_SIZE: 

line = self . etext_f ile . readline ( ) 
label_text = label_text + Unicode (line, 

'iso-8859-1') 
linecount = linecount + 1 

label_text = label_text + '\n\n\n' 

textbuffer. set_text (label_text ) 

self. textview. set_buf f er (textbuffer) 

def save_extracted_f ile (self , zipfile, filename) : 

"Extract the file to a temp directory for viewing' 
filebytes = zipfile . read ( filename) 
outfn = self .make_new_f ilename ( filename) 
if (outfn == ' ' ) : 

return False 
f = open (os .path. join (self . get_activity_root () , 

' tmp ' , outfn) , ' w ' ) 
try : 
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f. write (filebytes) 
finally: 

f . close ( ) 

def get_saved_page_number (self ) : 
global page 

title = self .metadata . get (' title ' , '') 
if title == ' ' or not title [ len (title) - l].isdigit() 

page = 
else : 

i = len(title) - 1 
newPage = ' ' 

while (title[i] .isdigit() and i > 0) : 
newPage = title [i] + newPage 
i = i - 1 
if title [i] == ' P' : 

page = int (newPage) - 1 
else : 

# not a page number; maybe a volume number, 
page = 

def save_page_number (self ) : 
global page 

title = self .metadata . get (' title ' , '') 
if title == '' or not title [ len (title) -1 ]. isdigit () : 

title = title + ' P' + str(page + 1) 
else : 

i = len(title) - 1 

while (title [i] .isdigit() and i > 0) : 

i = i - 1 
if title [i] == ' P' : 

title = title[0:i] + 'P' + str (page + 1) 
else : 

title = title + ' P' + str(page + 1) 
self .metadata [' title ' ] = title 

def read_f ile ( self , filename) : 
"Read the Etext file" 
global PAGE_SIZE, page 

if zipf ile . is_zipf ile ( filename) : 

self.zf = zipf ile . ZipFile (filename, 'r') 
self . book_f iles = self . zf . namelist ( ) 
self . save_ext r act ed_ file (self . zf , 

self .book_filesT0] ) 
currentFileName = os .path . j oin ( 

self . get_activity_root () , 

' tmp ' , self .book_f iles [ ] ) 
else : 

currentFileName = filename 

self . etext_f ile = open (currentFileName, "r" ) 

self . page_index = [ ] 

pagecount = 

linecount = 

while self . etext_f ile : 

line = self . etext_f ile . readline ( ) 

if not line: 
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break 
linecount = linecount + 1 
if linecount >= PAGE_SIZE: 

position = self . etext_file . tell ( ) 
self . page_index . append (position) 
linecount = 
pagecount = pagecount + 1 
if filename.endswithC.zip") : 

os . remove (currentFileName) 
self . get_saved_page_number ( ) 
self . show_page (page) 

self . read_toolbar . set_total_pages (pagecount + 1) 
self . read_toolbar . set_current_page (page) 

def make_new_f ilename ( self , filename) : 

partition_tuple = f ilename . rpartition ('/' ) 
return partition tuple [2] 

def write_f ile (self , filename) : 

"Save meta data for the file." 

self .metadata [' activity ' ] = self . get_bundle_id ( ) 

self . save_page_number ( ) 



This is the activity.info for this example: 



[Activity] 

name = Read ETexts II 

service_name = net . f lossmanuals . ReadEtextsActivity 

icon = read-etexts 

exec = sugar-activity ReadEtextsActivity2 .ReadEtextsActivity 

show_launcher = no 

activity version = 1 

mime_types = text/plain; application/zip 

license = GPLv2+ 



The line in bold is the only one that needs changing. When we run this new version 
this is what we'll see: 
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Produced by Anonymous Volunteers 



PRIDE AND PREJUDICE 



By Jane Austen 



Chapter 1 



It is a truth universally acknowledged, that a single man in possession 
of a good fortune, must be in want of a wife. 

However little known the feelings or views of such a man may be on his 
first entering a neighbourhood, this truth is so well fixed in the minds 



There are a few things worth pointing out in this code. First, have a look at this import: 

from gettext import gettext as _ 

We'll be using the gettext module of Python to support translating our Activity into 
other languages. We'll be using it in statements like this one: 

self. back. set_tooltip (_ ( ' Back ' ) ) 

The underscore acts the same way as the gettext function because of the way we 
imported gettext. The effect of this statement will be to look in a special translation file 
for a word or phrase that matches the key "Back" and replace it with its translation. If 
there is no translation file for the language we want then it will simply use the word 
"Back". We'll explore setting up these translation files later, but for now using gettext for 
all of the words and phrases we will show to our Activity users lays some important 
groundwork. 
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The second thing worth pointing out is that while our revised Activity has four toolbars 
we only had to create two of them. The other two, Activity and Edit, are part of the 
Sugar Python library. We can use those toolbars as is, hide the controls we don't need, 
or even extend them by adding new controls. In the example we're hiding the Keep 
and Share controls of the Activity toolbar and the Undo, Redo, and Paste buttons of 
the Edit toolbar. We currently do not support sharing books or modifying the text in 
books so these controls are not needed. Note too that the Activity toolbar is part of the 
ActivityToolbox. There is no way to give your Activity a toolbox that does not contain 
the Activity toolbar as its first entry. 

Another thing to notice is that the Activity class doesn't just provide us with a window. 
The window has a VBox to hold our toolbars and the body of our Activity. We install 
the toolbox using set_toolbox() and the body of the Activity using set_canvas(). 

The Read and View toolbars are regular PyGtk programming, but notice that there is a 
special button for Sugar toolbars that can have a tooltip attached to it, plus the View 
toolbar has code to hide the toolbox and ReadEtextsActivity2 has code to unhide it. 
This is an easy function to add to your own Activities and many games and other kinds 
of Activities can benefit from the increased screen area you get when you hide the 
toolbox. 

Metadata And Journal Entries 

Every Journal entry represents a single file plus metadata, or information describing 
the file. There are standard metadata entries that all Journal entries have and you can 
also create your own custom metadata. 

Unlike ReadEtextsActivity, this version has a write _file() method. 

def write_f ile (self , filename) : 

"Save meta data for the file." 

self .metadata [' activity ' ] = self . get_bundle_id ( ) 

self . save_page_number ( ) 

We didn't have a write_file() method before because we weren't going to update the file 
the book is in, and we still aren't. We will, however, be updating the metadata for the 
Journal entry. Specifically, we'll be doing two things: 

• Save the page number our Activity user stopped reading on so when he launches 
the Activity again we can return to that page. 

• Tell the Journal entry that it belongs to our Activity, so that in the future it will use 
our Activity's icon and can launch our Activity with one click. 

The way the Read Activity saves page number is to use a custom metadata property. 
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self .metadata [' Readcurrentpage ' ] = \ 

str (self ._document . get_page_cache ( ) . get_current_page ( ) ) 

Read creates a custom metadata property named Read_current_page to store the current 
page number. You can create any number of custom metadata properties just this 
easily, so you may wonder why we aren't doing that with Read Etexts. Actually, the 
first version of Read Etexts did use a custom property but in Sugar .82 or lower there 
was a bug in the Journal such that custom metadata did not survive after the computer 
was turned off. As a result my Activity would remember pages numbers while the 
computer was running, but would forget them as soon as it was shut down. XO laptops 
currently cannot upgrade to anything newer than .82, and when it is possible to 
upgrade it will be a big job for the schools. 

To get around this problem I created the following two methods: 

def get_saved_page_number (self ) : 
global page 

title = self .metadata . get (' title ' , '') 
if title == '' or not title [ len (title) -1 ]. isdigit () : 

page = 
else : 

i = len(title) - 1 
newPage = ' ' 

while (title[i] .isdigit() and i > 0) : 
newPage = title [i] + newPage 
i = i - 1 
if title [i] == ' P' : 

page = int (newPage) - 1 
else : 

# not a page number; maybe a volume number, 
page = 

def save_page_number (self ) : 
global page 

title = self .metadata . get (' title ' , '') 
if title == '' or not title [ len (title) -1 ]. isdigit () : 

title = title + ' P' + str(page + 1) 
else : 

i = len(title) - 1 

while (title[i] .isdigit() and i > 0) : 

i = i - 1 
if title [i] == ' P' : 

title = title[0:i] + 'P' + str (page + 1) 
else : 

title = title + ' P' + str(page + 1) 
self .metadata [' title ' ] = title 

save_page_number() looks at the current title metadata and either adds a page number to 
the end of it or updates the page number already there. Since title is standard metadata 
for all Journal entries the Journal bug does not affect it. 
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These examples show how to read metadata too. 

title = self .metadata . get (' title ' , '') 

This line of code says "Get the metadata property named title and put it in the variable 
named title, If there is no title property put an empty string in title. 

Generally you will save metadata in the write_file() method and read it in the read_file() 
method. 

In a normal Activity that writes out a file in write_file() this next line would be 
unnecessary: 

self .metadata [' activity ' ] = self . get_bundle_id ( ) 

Any Journal entry created by an Activity will automatically have this property set. In 
the case of Pride and Prejudice, our Activity did not create it. We are able to read it 
because our Activity supports its MIME type. Unfortunately, that MIME type, 
application/zip, is used by other Activities. I found it very frustrating to want to open a 
book in Read Etexts and accidentally have it opened in EToys instead. This line of 
code solves that problem. You only need to use Start Using... the first time you read a 
book. After that the book will use the Read Etexts icon and can be resumed with a 
single click. 

This does not at all affect the MIME type of the Journal entry, so if you wanted to 
deliberately open Pride and Prejudice with Etoys it is still possible. 

Before we leave the subject of Journal metadata let's look at all the standard metadata 
that every Activity has. Here is some code that creates a new Journal entry and updates 
a bunch of standard properties: 

def create_j ournal_entry (self , tempfile): 
j ournal_entry = datastore . create ( ) 
j ournal_title = self . selected_title 
if self . selectedvolurae != ' ' : 

j ournal_title += ' ' + _( 'Volume') + ' ' + \ 
self . selected_volume 
if self . selected_author != ' ' : 

j ournal_title = j ournal_title + ' , by ' + \ 
self . selected_author 
j ournal_entry . metadata [' title ' ] = j ournal_title 
j ournal_entry. metadata [' title_set_by_user ' ] = '1' 
j ournal_entry .metadata [' keep ' ] = '0' 
format = \ 

self . _books_toolbar . f ormat_combo .props .value 
if format == ' .djvu' : 

j ournal_entry .metadata [' mime_type ' ] = \ 
' image/vnd. djvu ' 
if format == ' .pdf ' or format == '_bw.pdf' : 
j ournal_entry . metadata [' mime_type ' ] = \ 
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' application/pdf ' 
journal_entry .metadata [ 'buddies ' ] = ' ' 
j ournal_entry .metadata [' preview ' ] = '' 
journal_entry .metadata [' icon-color ' ] = \ 

prof ile . getcolor ( ) .to_string() 
textbuffer = self . textview . get_buf f er ( ) 
j ournal_entry .metadata [' description ' ] = \ 

textbuffer. get_text (textbuffer . get_start_iter ( ) , 

textbuf f er . get_end_iter ( ) ) 
j ournal_entry . f ile_path = tempfile 
datastore . write ( j ournal_entry) 
os . remove (tempfile) 
self ._alert (_(' Success ') , self . selected_title + \ 

_(' added to Journal.')) 

This code is taken from an Activity I wrote that downloads books from a website and 
creates Journal entries for them. The Journal entries contain a friendly title and a full 
description of the book. 

Most Activities will only deal with one Journal entry by using the read_file() and 
write_file() methods but you are not limited to that. In a later chapter I'll show you how 
to create and delete Journal entries, how to list the contents of the Journal, and more. 

We've covered a lot of technical information in this chapter and there's more to come, 
but before we get to that we need to look at some other important topics: 

• Putting your Activity in version control. This will enable you to share your code 
with the world and get other people to help work on it. 

• Getting your Activity translated into other languages. 

• Distributing your finished Activity. (Or your not quite finished but still useful 
Activity). 
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-L -L • Add Your Activity Code To Version 
Control 

What Is Version Control? 

"If I have seen further it is only by standing on the shoulders of giants." 

Isaac Newton, in a letter to Robert Hooke. 

Writing an Activity is usually not something you do by yourself. You will usually have 
collaborators in one form or another. When I started writing Read Etexts I copied 
much of the code from the Read Activity. When I implemented text to speech I 
adapted a toolbar from the Speak Activity. When I finally got my copied file sharing 
code working the author of Image Viewer thought it was good enough to copy into 
that Activity. Another programmer saw the work I did for text to speech and thought 
he could do it better. He was right, and his improvements got merged into my own 
code. When I wrote Get Internet Archive Books someone else took the user interface 
I came up with and made a more powerful and versatile Activity called Get Books. 
Like Newton, everyone benefits from the work others have done before. 

Even if I wanted to write Activities without help I would still need collaborators to 
translate them into other languages. 

To make collaboration possible you need to have a place where everyone can post their 
code and share it. This is called a code repository. It isn't enough to just share the latest 
version of your code. What you really want to do is share every version of your code. 
Every time you make a significant change to your code you want to have the new 
version and the previous version available. Not only do you want to have every 
version of your code available, you want to be able to compare any two versions your 
code to see what changed between them. This is what version control software does. 

The three most popular version control tools are CVS, Subversion, and Git. Git is the 
newest and is the one used by Sugar Labs. While not every Activity has its code in the 
Sugar Labs Git repository (other free code repositories exist) there is no good reason not 
to do it and significant benefits if you do. If you want to get your Activity translated 
into other languages using the Sugar Labs Git repository is a must. 
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Git Along Little Dogies 

Git is a distributed version control system. This means that not only are there copies 
of every version of your code in a central repository, the same copies exist on every 
user's computer. This means you can update your local repository while you are not 
connected to the Internet, then connect and share everything at one time. 

There are two ways you will interact with your Git repository: through Git commands 
and through the website at http : //git . sugarlab s , org/. We'll look at this website first. 

Go to http : //git . sugarlab s . or g/ and click on the Projects link in the upper right corner: 



Home Projects Search About Register Login 



sugarlabs 



You will see a list of projects in the repository. They will be listed from newest to 
oldest. You'll also see a New Project link but you'll need to create an account to use 
that and we aren't ready to do that yet. 



New project 



karma_English_Alphabet_Puzzle_Solving 

A simple English Alphabet lesson 
Categories; none 



karma_Conozco- Uruguay 

A simple lesson for learning the geography of Uruguay 
Categories: none 



k ar m a_ad d i n g_u p_t o_1 0_s v g 

A simple game for learning how to add up to 1 □ 
Categories: none 



supervisor 

A privileged service which supervises activity run cycle, exposes startup progress, upgr 

infrastructure. 

Categories: service 
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If you use the Search link in the upper right corner of the page you'll get a search form. 
Use it to search for "read etexts". dick on the link for that project when you find it. You 
should see something like this: 




readetexts 

Read Etexts is an alternative to the regular Read Activity which can read Project Gutenberg pla 
stopgap until Read itself can use this format. Plain text files are by far the most popular Gutent 
thousands of free books in many languages. 

In addition to the normal ebook reader functions this reader adds text to speech with karaoke st 
needs speech-dispatcher installed, which is not currently part of the Sugar distribution but even 



Activities 



^ alsroot deleted repository readetexts/gst-plugins-espeak 



SATURDAY MARCH 07 



17:58 L alsm °t deleted repository readetexts/bugfix 



FRIDAY FEBRUARY \ 



22:49 jdsimmons added committer pootle to readetexts/mainline 

This page lists some of the activity for the project but I don't find it particularly useful. 
To get a much better look at your project start by clicking on the repository name on the 
right side of the page. In this case the repository is named mainline. 



Labels: activities 

License: GNU General Public License version 2(GPLv2) 

Owner: jdsimmons 

Created: 18 Jan 00:38 

Repositories 

Q mainline 

|i jtfeimmons 
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You'll see something like this at the top of the page: 




Overview Commits Source Tree Comments (01 Merge requests(O) 



"mainline" repository in readetexts 



Public clone url: git: //git, sugarlabs.org/readetexts/mainline, git More inFo... 

You can clone this repository with the following command: 

git clone git://git .sugarlabs . org/readetexts/mainline. git 

HTTP clone url: http://git.sugarlabs.org/git/readetexts/rrainline.git More info.. 

You can clone this repository with the following command: 

git clone http://git.sugarlabs.org/git/readetexts/riiainline, git 

(nolelhai cloning over HTTP k slighliy slower, bui iseful F yoi/re behind a Firewall) 



Activities O 



JNDAY JANUARY IB 



23:04 L J dsirnmotls committed 7638697a to readetexts/mainline 

modified: ReadEtextsActivity.py 



This page has some useful information on it. First, have a look at the Public clone url 
and the HTTP clone url. You need to click on More info... to see either one. If you 
run either of these commands from the console you will get a copy of the git repository 
for the project copied to your computer. This copy will include every version of every 
piece of code in the project. You would need to modify it a bit before you could share 
your changes back to the main repository but everything would be there. 

The list under Activities is not that useful, but if you click on the Source Tree link 
you'll see something really good: 
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Tree of mainline repository in readetexts 



I main ling 

G -gi" 

.J. ad 
J au 

□ gu- 
Q he 
C3loc 
J Mi" 
Q NE 

□ P9' 
C2 pa 
J Re 

□ reE 
Q reE 

□ rtfconvert.py 



Q .gitignore 


01 Sop 23:16 


modified : 


.gitignore modified: MAN! 


C3 activity/ 


22 Nov 20:E2 


modified: 


ReadEtextsActivity .py moi 


Q ausextract.py 


30 May 21:52 


modified : 


ReadEtextsActivity . py moi 


□ gutextract.py 


30 May 21:52 


modified: 


ReadEtextsActivity .py moi 


Q help.txt 


22 Nov 20:E2 


modified : 


ReadEtextsActivit y . py moi 


C2 locale.'' 


06 Dec 23:39 


new file: 


locale/kos/LCJ-IESSAGES/o 


J MANIFEST 


22 Nov 23:31 


modified: 


MANIFEST modified: tocali 


Q NEWS 


01 Mar 20:48 


Initial import 


_J pgconvert.py 


29 Nov 22:34 


modified: 


ReadEtextsActivity .py moi 


Ql paf 


1 1 Nov 05:E5 


Commit from Sugar Labs: Translatioi 


J ReadEtextsActivity.py 


29 Nov 22:34 


modified : 


ReadEtextsActivit y . py moi 


□ readsidebar.py 


25JuM4:48 


modified: 


ReadEtextsAetivity .py moi 


_] readtoolbar.py 


06 Dec 23:39 


new file: 


locale/kos/LC_MESSAGES/o 



22 Nov 23:26 



modified: ReadEtextsAetivity .py moi 



Here is a list of every file in the project, the date it was last updated, and a comment on 
what was modified, dick on the link for ReadEtextsActivity.py and you'll see this: 
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Project Overview 



Repositories 
Overview Commits Source Tree Comments (□) Merge requests(O) 

Blob of ReadEtextsActivity . py (raw blob data) 

I mainline ! ReadEtextsActivity. py 



1 

2 

3 

4 

5 

6 

7 



9 

IS 

11 

12 

13 

14 

15 

18 

17 

IS 

19 

20 

21 

22 

23 

24 

25 

2B 

27 

28 



#! /usr/bin/env python 

# Copyright (O 2003, 20Q9 James D, Simmons 

# This program is free software; you can redistribute it and/or modify 

# it under the terms of the GNU General Public License as published by 

# the Free Software Foundation; either version 2 of the License., or 

# (at your option) any later version. 
# 

# This program is distributed in the hope that it will be useful, 

# but WITHOUT ANY WARRANTY; without even the inplied warranty of 
ft MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE . See the 

# GNU General Public License for more details. 
# 

# You should have received a copy of the GNU General Public License 

# along with this program.; if not, write to the Free Software 

# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 
import os 

import logging 

import tempfile 

import time 

import zipfile 

import pygtk 

pygtk. require! ' 2.0' ) 

import gtk 

import string 

from sugar, graphics import style 

from sugar import profile 



This is the latest code in that file in pretty print format. Python keywords are shown in 
a different color, there are line numbers, etc. This is a good page for looking at code on 
the screen, but it doesn't print well and it's not much good for copying snippets of code 
into Eric windows either. For either of those things you'll want to click on raw blob 
data at the top of the listing: 



#! /usr/bin/env python 

# Copyright (C) 20O8, 2009 James D, Simmons 
# 

# This program is free software; you can redistribute it and/or modify 

# it under the terms of the GNU General Public License as published by 

# the Free Software Foundation; either version 2 of the License; or 

# (at your option) any later version. 
# 

# This program is distributed in the hope that it will be useful; 

# but WITHOUT ANY WARRANTY; without even the implied warranty of 

# MERCHANTABILITY or FITNESS FDR A PARTICULAR PURPOSE. See the 

# GNU General Public License for more details. 
# 

# You should have received a copy of the GNU General Public License 

# along with this program; if not, write to the Free Software 

# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 
import os 

import logging 

import tempfile 

import time 

import zipfile 

import pygtk 

pygtk, require! '2,0' ) 

import gtk 

import string 

from sugar, graphics import style 

from sugar import profile 

from sugar, activity import activity 

from sugar import network 

from sugar, datastore import datastore 

from suaar, graphics, alert import NotifvAlert 

We're not done yet. Use the Back button to get back to the pretty print listing and click 
on the Commits link. This will give us a list of everything that changed each time we 
committed code into Git: 
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Overview Commits Source Tree Comments (0) Merge requests(O) 



Commitlog for mainline:master in readetexts 



SUNDAY DECEMBER 06 



23:39 L James Simmons committed cc81 203 

new file: locale/ kos/LC_MESSAGES/org .laptop . sugar. ReadEtextsActivity. mo 



SUNDAY NOVEMBER 



James Simmons committed 720affc 
modified: ReadEtextsActivity.py 



23 : 3i James Simmons committed 35bf41 7 

modified: MANIFEST 

L James Simmons committed dc6322a 
modified: ReadEtextsActivity.py 

~~ James Simmons committed f9cd855 
modified: ReadEtextsActivity.py 

You may have noticed the odd combination of letters and numbers after the words 
James Simmons committed. This is a kind of version number. The usual practice 
with version control systems is to give each version of code you check in a version 
number, usually a simple sequence number. Git is distributed, with many separate 
copies of the repository being modified independently and then merged. That makes 
using just a sequential number to identify versions unworkable. Instead, Git gives each 
version a really, really large random number. The number is expressed in base 16, 
which uses the symbols 0-9 and a-f. What you see in green is only a small part of the 
complete number. The number is a link, and if you click on it you'll see this: 
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Overview Commits Source Tree Comments (0) Merge request s(0) 

Commit cc81 2030cbf3ec8a51 4275fb97c2ca425b21 6a2f 

Date: Sun Dec 06 23:39:56+0000 2009 

Committer: James Simmons (jim@simmons.olpc) 

Author: James Simmons (jim@simmons.olpc) 

Commit SHA1: ccS1 2030cbf3ec8a514275fb97c2ca425b21 6a2f 

Tree SHA1: aa0f8aadc7636b9e75047a85c534bf234c993365 



new file: locale/kos/LC MESSAGES/org . laptop. sugar . ReadEtextsActivity. mo 

new Tile: locale/kos/acTivity.linfo 

new file: locale/tzo/LC HESSAGES/org . laptop. sugar . ReadEtextsActivity. mo 

new file: locale/tzo/acTivity.linfo 

modified: readtoolbar.py 

Modify speech toolbar to save and restore speech settings. 



Commit diff 



Comments (0) 



readtoolbar, py 29 --+++++++++++++++++++++++++++ 

locale/tzo/actLvity.linfo 2 ++ 

locale/tzo/LC_MESSAGES/org . laptop. sugar. ReadEtextsActivity.mo B 

locale/kos/activity.linfo 2 ++ 

locale/ kos/LC_MESSAGES/org , laptop. sugar, ReadEtextsActivity.mo Q 

Commit diff 

locale/ko&''LC_MESSAGES/org. laptop, sugar. ReadEtextsActivity.mo 

At the top of the page we see the complete version number used for this commit. 
Below the gray box we see the full comment that was used to commit the changes. 
Below that is a listing of what files were changed. If we look further down the page we 
see this: 
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readtoolbar.py 



is is # along with this program; it not, write to ths Fres Software 

IS 16 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, HA 3211Q-L3E1 

17 17 

is import os 

13 19 import logging 

19 20 from gettext import gettext as _ 

20 21 import re 



416 416 

417 417 

418 418 
419 

420 419 

421 1 420 

422 421 

427 427 

428 428 

429 429 
430 

431 430 

432 431 

433 432 



combotool.show() 

self .pitchadj = gtk. Adjustment [0, -IBS, IBB, 1, 10, B) 

self . pitchad j , connect ( " value_changed" , self . pitch_ad] usted_cb) 

pitchbar = gtk. HScale(self .pitchadj) 

pitchbar . set_draw_value(False) 

pitchbar. set jjpdatejoUcylgtk. UPDATE JHSCONTINUOUS) 



_ 



h 



pitchbar, show() 

self. rateadj = gtk. Adjustment (B, -IBB, IBB, 1, IB, B) 

self. rateadj , connect ("value_changed", self, rate_adjusted_cb) 

ratebar = gtk,HScale(self, rateadj) 

ratebar , set_draw_value( False) 

ratebar.set_update_policy(gtk.UPDATE_DISCON"nNUOUS) 



453 453 def pitch_adjusted_cb(self , get): 

454 454 speech, pitch = int( get. value) 

455 455 speech, say(_("pitch adjusted")) 
456 f = open (os, path, join (self , activity,get_activity_root(), 'insta 

This is a diff report which shows the lines that have changed between this version and 
the previous version. For each change it shows a few lines before and after the change 
to give you a better idea of what the change does. Every change shows line numbers 
too. 

A report like this is a wonderful aid to programming. Sometimes when you're working 
on an enhancement to your program something that had been working mysteriously 
stops working. When that happens you will wonder just what you changed that could 
have caused the problem. A diff report can help you find the source of the problem. 

By now you must be convinced that you want your project code in Git. Before we can 
do that we need to create an account on this website. That is no more difficult than 
creating an account on any other website, but it will need an important piece of 
information from us that we don't have yet. Getting that information is our next task. 
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Setting Up SSH Keys 

To send your code to the Gitorious code repository you need an SSH public/private 
key pair. ! SSH is a way of sending data over the network in encrypted format. (In 
other words, it uses a secret code so nobody but the person getting the data can read it). 
Public/private key encryption is a way of encrypting data that provides a way to 
guarantee that the person who is sending you the data is who he claims to be. 

In simple terms it works like this: the SSH software generates two very large numbers 
that are used to encode and decode the data going over the network. The first number, 
called the private key, is kept secret and is only used by you to encode the data. The 
second number, called the public key, is given to anyone who needs to decode your 
data. He can decode it using the public key; there is no need for him to know the 
private key. He can also use the public key to encode a message to send back to you 
and you can decode it using your private key. 

Git uses SSH like an electronic signature to verify that code changes that are supposed 
to be coming from you actually are coming from you. The Git repository is given your 
public key. It knows that anything it decodes with that key must have been sent by 
you because only you have the private key needed to encode it. 

We will be using a tool called OpenSSH to generate the public and private keys. This 
is included with every version of Linux so you just need to verify that it has been 
installed. Then use the ssh-keygen utility that comes with OpenSSH to generate the 
keys: 

[jim@olpc2 ~]$ ssh-keygen 
Generating public/private rsa key pair. 
Enter file in which to save the key ( /home/ j im/ . ssh/id_rsa) : 

By default ssh-keygen generates an RSA key, which is the kind we want. By default it 
puts the keyfiles in a directory called lyourhomel. ssh and we want that too, so DO NOT 
enter a filename when it asks you to. Just hit the Enter key to continue. 

[jim@olpc2 ~]$ ssh-keygen 
Generating public/private rsa key pair. 

Enter file in which to save the key ( /home/ j im/ . ssh/id_rsa) : 
Created directory ' /home/ j im/ . ssh ' . 
Enter passphrase (empty for no passphrase) : 

Now we DO want a passphrase here. A passphrase is like a password that is used with 
the public and private keys to do the encrypting. When you type it in you will not be 
able to see what you typed. Because of that it will ask you to type the same thing again, 
and it will check to see that you typed them in the same way both times. 
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[jim@olpc2 ~]$ ssh-keygen 
Generating public/private rsa key pair. 
Enter file in which to save the key (/h 
Created direetorv ' /home /i ira/ . ssh ' . 



Created directory ' /home/ j im/ . ssh 

Enter passphrase (empty for no passphrase 



home/ j im/ . ssh/id_rsa) : 



has been saved in /home/jim/ 
85:c7 : 4c: 9e 



Enter same passphrase again: 

Your identification has been saved 

Your public key has be"' ! 

The key fingerprint is . 

d0:fe:c0:0c:le:72:56:7a:19:cd:f3: 

j im@olpc2 . simmons 

The key's randomart image is: 

^-- r RSA 2048] + 

oo E=. 
+ o+ .+=. 
. B + o . oo 
= 



in /home/ j im/ . ssh/id_rsa . 
1 ^--i ss h/id_rsa . pub . 



1! 



+ -- 



When choosing a passphrase remember that it needs to be something you can type 
reliably without seeing it and it would be better if it was not a word you can find in the 
dictionary, because those are easily broken. When I need to make a password I use the 
tool at http: //www. multicians , org/thv v/gpw. html. This tool generates a bunch of 
nonsense words that are pronounceable. Pick one that appeals to you and use that. 

Now have a look inside the .ssh directory. By convention every file or directory name 
that begins with a period is considered hidden by Linux, so it won't show up in a 
GNOME file browser window unless you use the option on the View menu to Show 
Hidden Files. When you display the contents of that directory you'll see two files: 
id_rsa and id_rsa.pub. The public key is in id_rsa.pub. Try opening that file with 
gedit (Open With Text Editor) and you'll see something like this: 



Id rsa. pub [~/.ssri) ■ gedit 



Rle Edit view search Tools Documents Help 



New Open Save 



Hurt. . 



Undo Redo I '_ut Lop 



% & m. 

Paste Find Replace 



|_J id_rsa.pub 

SSH- rsa AWWE3NzaClyt3EAAfl*EIWUU>gOveR23a_//l^yl.3TXEZDrCSXR2VpW6HCeMXQqCflVtfiElU-tNra«Fr6 

-tc ZKWCtAjyU rfei vn7 kZJY k/fje/ f 2 j spwBOyYf 

tTisb KJVWoy kPBFP dHp Jet5 j I* U j 41 Cy KVpc CeYoAlxsp j xMhWOoeh 3Yd PDWn USe F50w3nO qoSn oM3u0u rvJAtM*2 PC5XPc ARX 

*d BblSWTLK H6Bh pv3d TVDnPNOKhC Ii9tvSpiSp Wild KpMf / 5HsCJ KKzC 2yh BiGLTnV5«iw'T2 c Jqc 5641 T/v3KF-t«7SsX5U 31B6Wy+»iirg/ 

IE 3Ys DBQc PZ1 DWa993J rwrC rXRellb Yn5pKJ4DkCD=r= j lmgnip c2 . slmrnns 
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When you create your account on git, sugarlab s. org there will be a place where you can 
add your public SSH key. To do that use Select All from the Edit menu in gedit, then 
Copy and Paste into the field provided on the web form. 

Create A New Project 

I'm going to create a new Project in Git for the examples for this book. I need to log in 
with my new account and click the New Project link we saw earlier. I get this form, 
which I have started filling in: 

Create a new project 

Title 



Make Your Own Sugar Activities Examples 



Slug (Tor urls etc) 



myo-sugar-activities-examples 



Categories (space separated) 



activities 



License 

GNU General PuPlic License vi^J 

The Title is used on the website, the Slug is a shortened version of the title without 
spaces used to name the Git repository. Categories are optional. License is GPL v2 for 
my projects. You can choose from any of the licenses in the list for your own Projects, 
and you can change the license entry later if you want to. You will also need to enter a 
Description for your project. 

Once you have this set up you'll be able to click on the mainline entry for the Project 
(like we did with Read Etexts before) and see something like this: 
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Repositories 
Overview Commits ScuiceTree Comments (0) Merge requests (0) 



"mainline" repository in Make Your Own Sugar Activities Book Examples 

Public clone url: git; //git. strgarlabs.org/myo-sugar-aetivities-exariplevrrain line, git nuts Ms. .. 



You cart do re th i s repo sito ry with ihe bl lowing command ; 

git clone git://git.sLtgarlabs.org/»yD-5ugar-activities-e>raiiples/iainline.git 

HTTP clone url: tittp://git,sugarlabs, Drg/git/myo-sugar-activities-exanples/inainline.git r.bro infa.. 

You can do ne th i s repo sito ry with ihe bl low ing command : 

git clone nttf>: //git, sua.ariabi.org/glt/riyo- sugar -activities- exanpies/riamilne. git 

(note thai coring ever HTTP Bs*grril/ &kwer. bui Lsetuli yoi/^behoiafre^l) 

Puih url! gitoriousggit.sugarlabs. orgimyo-sugar-actiuities-exanples/irainline. gitftfai. irfo..] 



You can run -git push gitorious^glt .sugarlabs.org myo-sugar- activities -examples/mainline, git", or you es 

tit renote add origin gitorious&jit. sugarlabs.orgiriyO'Suqar-activitie'S-eKaiiples/riainline.git 
to push trie laster branch to the origin remite we added above: 
git push origin master 
* after that yDU can. just do; 
git push 



Activities E3 

The next step is to convert our project files into a local Git repository, add the files to it, 
then push it to the repository on git. sugarlab s. org. We need to do this because you 
cannot clone an empty repository, and our remote repository is currently empty. To get 
around that problem we'll push the local repository out to the new remote repository we 
just created, then clone the remote one and delete our existing project and its Git 
repository. From then on we'll do all our work in the cloned repository. 

This process may remind you of the Edward Albee quote, "Sometimes a person has to 
go a very long distance out of his way to come back a short distance correctly". 
Fortunately we only need to do it once per project. Enter the commands shown below 
in bold after making you project directory the current one: 

git init 

Initialized empty Git repository in 
/home/ j im/olpc/bookexamples/ .git/ 
git add *.py 
git add activity 
git add MANIFEST 
git add .gitignore 

git commit -a -m "Create repository and load" 
[master (root-commit) 727bfe8] Create repository and load 

9 files changed, 922 insertions ( + ) , deletions (-) 

create mode 100644 .gitignore 

create mode 100644 MANIFEST 

create mode 100755 ReadEtexts .py 

create mode 100644 ReadEtextsActivity . py 

create mode 100644 ReadEtextsActivity2 . py 

create mode 100644 activity/activity . info 
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create mode 100644 activity/read-etexts . svg 
create mode 100755 setup. py 
create mode 100644 toolbar. py 

I have made an empty local Git repository with git init, then I've used git add to add 
the important files to it. (In fact git add doesn't actually add anything itself; it just tells 
Git to add the file on the next git commit). Finally git commit with the options shown 
will actually put the latest version of these files in my new local repository. 

To push this local repository to git, sugarlab s. org we use the commands from the web 
page: 

git remote add origin \ 
gitorious@git . sugarlabs . org : \ 
myo-sugar-activi ties-examples/mainline . git 
git push origin master 

Counting objects: 17, done. 

Compressing objects: 100% (14/14), done. 

Writing objects: 100% (15/15), 7.51 KiB, done. 

Total 15 (delta 3), reused (delta 0) 

To gitorious@git. sugarlabs. org : myo-sugar-activi ties -examples/ 

mainline . git 

2cb3ale .. 70078 9d master -> master 
=> Syncing Gitorious... 
Heads up: head of changed to 

700789d3333a7257999d0a69bdcafb840e6adc09 on master 
Notify cia.vc of 727bf e81 9d5b7b70f 4f 2b31d02f 5562709284ac4 on 
myo-sugar-activi ties -examples 

Notify cia.vc of 70078 9d3333a7257 999d0a69bdcafb84 0e6adc09 on 
myo-sugar-activi ties -examples 
[OK] 
rm * 

rm activity -rf 
rm .git -rf 
cd ~ 

rm Activity/ReadEtextsII 
mkdir olpc 
cd olpc 

mkdir bookexamples 
cd bookexamples 
git clone \ 

git: //git . sugarlabs . org/\ 

myo-sugar-activi ties-examples/mainline . git 
Initialized empty Git repository in 
/home/ j im/ olpc /bookexamples /mainline/ .git/ 
remote: Counting objects: 18, done, 
remote: Compressing objects: 100% (16/16), done, 
remote: Total 18 (delta 3), reused (delta 0) 
Receiving objects: 100% (18/18), 8.53 KiB, done. 
Resolving deltas: 100% (3/3), done. 
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The lines in bold are the commands to enter, and everything else is messages that Git 
sends to the console. I've split some of the longer Git commands with the backslash (\ ) 
to make them fit better on the printed page, and wrapped some output lines that would 
normally print on one line for the same reason. It probably isn't clear what we're doing 
here and why, so let's take it step by step: 

• The first command git remote add origin tells the remote Git repository that we 
are going to send it stuff from our local repository. 

• The second command git push origin master actually sends your local Git 
repository to the remote one and its contents will be copied in. When you enter 
this command you will be asked to enter the SSH pass phrase you created in the 
last section. GNOME will remember this phrase for you and enter it for every Git 
command afterwards so you don't need to. It will keep doing this until you log out 
or turn off the computer. 

• The next step is to delete our existing files and our local Git repository (which is 
contained in the hidden directory .git). The rm .git -rf means "Delete the directory 
.git and everything in it", rm is a Unix command, not part of Git. If you like you 
can delete your existing files after you create the cloned repository in the next step. 
Note the command rm Activity/ReadEtextsII, which deletes the symbolic link to 
our old project that we created by running ./setup.py dev. We'll need to go to our 
new cloned project directory and run that again before we can test our Activity 
again. 

• Now we do the git clone command from the web page. This takes the remote Git 
repository we just added our MANIFEST file to and makes a new local repository 
in directory A/oMr/iome/olpc/bookexamples/mainline. 

Finally we have a local repository we can use. Well, not quite. We can commit our code 
to it but we cannot push anything back to the remote repository because our local 
repository isn't configured correctly yet. 

What we need to do is edit the file config in directory .git in 

/i/OMr/zome/olpc/bookexamples/mainline. We can use gedit to do that. We need to 
change the url= entry to point to the Push url shown on the mainline web page. When 
we're done our config file should look like this: 

[core] 

repositoryf ormatversion = 

filemode = true 

bare = false 

logallref updates = true 
[remote "origin"] 

url = gitorious@git.sugarlabs.org: 
myo-sugar-activi ties-examples/mainline . git 

fetch = +ref s/heads/* : ref s/remotes/origin/* 
[branch "master"] 
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remote = origin 

merge = ref s/heads/master 

The line in bold is the only one that gets changed. It is split here to make it fit on the 
printed page. In your own files it should all be one line with no spaces between the 
colon(:) that ends the first line and the beginning of the second line. 

From now on anyone who wants to work on our project can get a local copy of the Git 
repository by doing this from within the directory where he wants the repository to go: 

git clone git : //git . sugarlabs . org/\ 
myo-sugar-activi ties-examples/mainline . git 

He'll have to change his .git/config file just like we did, then he'll be ready to go. 

Everyday Use Of Git 

While getting the repositories set up to begin with is a chore, daily use is not. There are 
only a few commands you'll need to work with. When we left off we had a repository 
in /j/owr/jowe/olpc/bookexamples/mainline with our files in it. We will need to add 
any new files we create too. 

We use the git add command to tell Git that we want to use Git to store a particular file. 
This doesn't actually store anything, it just tells Git our intentions. The format of the 
command is simply: 

git add file_or_directory_name 

There are files we don 't want to add to Git, to begin with those files that end in .pyc. If 
we never do a git add on them they'll never get added, but Git will constantly ask us 
why we aren't adding them. Fortunately there is a way to tell Git that we really, really 
don't want to add those files. We need to create a file named .gitignore using gedit and 
put in entries like this: 

* .pyc 

* .e4p 

* . zip 

. eric4pro j ect/ 
. ropepro j ect/ 

These entries will also ignore project files used by Eric and zip files containing ebooks, 
Once we have this file created in the mainline directory we can add it to the repository: 

git add .gitignore 

git commit -a -m "Add .gitignore file" 
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From now on Git will no longer ask us to add .pyc or other unwanted files that match 
our patterns. If there are other files we don't want in the repository we can add them to 
.gitignore either as full file names or directory names or as patterns like *.pyc. 

In addition to adding files to Git we can remove them too: 

git rm filename 

Note that this just tells Git that from now on it will not be keeping track of a given 
filename, and that will take effect at the next commit. Old versions of the file are still in 
the repository. 

If you want to see what changes will be applied at the next commit run this: 

git status 

# On branch master 

# Changed but not updated: 

# (use "git add <file>..." to update what will 

# be committed) 
# 

# modified: ReadEtextsActivity .py 
# 

no changes added to commit (use "git add" and/or 
"git commit -a") 

Finally to put your latest changes in the repository use this: 

git commit -a -m "Change use of instance directory to tmp" 

Created commit a687b27: Change use of instance 
directory to tmp 
1 files changed, 2 insertions ( + ) , 2 deletions (-) 

If you leave off the -m an editor will open up and you can type in a comment, then save 
and exit. Unfortunately by default the editor is vi, an old text mode editor that is not 
friendly like gedit. 

When we have all our changes done we can send them to the central repository using 
git push: 

git push 

Counting objects: 5, done. 

Compressing objects: 100% (3/3), done. 

Writing objects: 100% (3/3), 322 bytes, done. 

Total 3 (delta 2), reused (delta 0) 

To gitorious@git.sugarlabs.org: 

myo- sugar-activities -examples /mainline .git 

700789d. .a687b27 master -> master 
=> Syncing Gitorious . . . 
Heads up: head of changed to 

a687b27e2f 034e5al7d2ca2fe9f2787c7f 633e64 on master 
Notify cia.vc of a687b27e2f 034e5al7d2ca2f e9f 27 87c7f 633e64 
on myo-sugar-activities-examples 
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[OK] 



We can get the latest changes from other developers by doing git pull: 



git pull 

remote: Counting objects: 17, done. 

remote: Compressing objects: 100% (14/14), done. 

remote: Total 15 (delta 3), reused (delta 0) 

Unpacking objects: 100% (15/15), done. 

From gitoriousSgit. sugarlabs .org: 

myo- sugar- activities -examples /mainline 

2cb3ale .. 70078 9d master -> origin/master 
Updating 2cb3ale .. 70078 9d 
Fast forward 



. gitignore 
MANIFEST 



Re a 
Rea 
Rea 
+ + + + 
act 
act 
set 
too 
9 f 
ere 
ere 
ere 
ere 
ere 
ere 
ere 
ere 



dEtext 
dEtext 
dEtext 
++++++ 
ivity/ 
ivity/ 
up.py 
lbar . p 
iles c 
ate mo 
ate mo 
ate mo 
ate mo 
ate mo 
ate mo 
ate mo 
ate mo 



s.py 

sActiv 

sActiv 

++++++ 

activi 

read-e 

Y 
hanged, 

de 100* 
de 100 
de 100 
de 100 
de 100 
de 100 
de 100 
de 100 6 



6 + 
244 +■ 



182 +++++++++++++++++++++++++++ 
182 +++++++++++++++++++++++++++ 
311 +++++++++++++++++++++++++++ 



+ + 

+++++++++++ 
+ + + 

++++++++++++++++++++ 
+ ) , 241 deletions (-) 



ty.py 

ty2.py 
+ + 

y . info | 9 
exts . svg | 71 
21 
136 
921 insertions 
44 .gitignore 
55 ReadEtexts .py 
44 ReadEtextsActivity .py 
44 ReadEtextsActivity2 .py 
44 activity/activity . info 
44 activity/read-etexts . svg 
55 setup. py 
44 toolbar. py 
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J^Ztm Going International With Pootle 

Introduction 

The goal of Sugar Labs and One Laptop Per Child is to educate all the children of the 
world, and we can't do that with Activities that are only available in one language. It is 
equally true that making separate versions of each Activity for every language is not 
going to work, and expecting Activity developers to be fluent in many languages is not 
realistic either. We need a way for Activity developers to be able to concentrate on 
creating Activities and for those who can translate to just do that. Fortunately, this is 
possible and the way it's done is by using gettext. 

Getting Text With gettext 

You should remember that our latest code example made use of an odd import: 

from gettext import gettext as _ 

The "_()" function was used in statements like this: 

self. back. set_tooltip (_ ( ' Back ' ) ) 

At the time I explained that this odd looking function was used to translate the word 
"B ack" into other languages, so that when someone looks at the B ack button's tool tip 
he'll see the text in his own language. I also said that if it was not possible to translate 
this text the user would see the word "B ack" untranslated. In this chapter we'll learn 
more about how this works and what we have to do to support the volunteers who 
translate these text strings into other languages. 

The first thing you need to learn is how to properly format the text strings to be 
translated. This is an issue when the text strings are actual sentences containing 
information. For example, you might write such a message this way: 

message = _("User ") + username + \ 
_(" has joined the chat room.") 

This would work, but you've made things difficult for the translator. He has two 
separate strings to translate and no clue that they belong together. It is much better to 
do this: 

message = _("User %s has joined the chat room.") % \ 
username 
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If you know both statements give the same resulting string then you can easily see why 
a translator would prefer the second one. Use this technique whenever you need a 
message that has some information inserted into it. When you use it, try and limit 
yourself to only one format code (the %s) per string. If you use more than one it can 
cause problems for the translator. 

Going To Pot 

Assuming that every string of text a user might be shown by our Activity is passed 
through "_()" the next step is to generate a pot file. You can do this by running setup.py 
with a special option: 

./setup.py genpot 

This creates a directory called po and puts a file ActivityName.pot in that directory. In 
the case of our example project ActivityName is ReadEtextsII. This is the contents of 
that file: 

# SOME DESCRIPTIVE TITLE. 

# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER 

# This file is distributed under the same license as the 

# PACKAGE package. 

# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. 
# 

#, fuzzy 

msgid "" 

msgstr "" 

"Project-Id-Version: PACKAGE VERSION\n" 

"Report-Msgid-Bugs-To: \n" 

"POT-Creation-Date: 2010-01-06 18 : 31-0 600\n" 

"PO-Revision-Date: YEAR-MO-DA HO :MI+ZONE\n" 

"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" 

"Language-Team: LANGUAGE <LL@li . org>\n" 

"MIME-Version: 1.0\n" 

"Content-Type: text/plain; charset=CHARSET\n" 

"Content-Transfer-Encoding: 8bit\n" 

#: activity/activity . info : 2 
msgid "Read ETexts II" 
msgstr "" 

# : toolbar . py : 34 
msgid "Back" 
msgstr "" 

#: toolbar .py: 40 
msgid "Forward" 
msgstr "" 

#: toolbar . py: 115 
msgid "Zoom out" 
msgstr "" 
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#: toolbar .py: 120 
msgid "Zoom in" 
msgstr "" 

#: toolbar . py : 130 
msgid "Fullscreen" 
msgstr "" 

#: ReadEtextsActivity2 .py : 34 
msgid "Edit" 
msgstr "" 

#: ReadEtextsActivity2 .py : 38 
msgid "Read" 
msgstr "" 

#: ReadEtextsActivity2 .py : 46 
msgid "View" 
msgstr "" 

This file contains an entry for every text string in our Activity (as msgid) and a place to 
put a translation of that string (msgstr). Copies of this file will be made by the Pootle 
server for every language desired, and the msgstr entries will be filled in by volunteer 
translators. 

Going To Pootle 

Before any of that can happen we need to get our POT file into Pootle. The first thing 
we need to do is get the new directory into our Git repository and push it out to 
Gitorious. You should be familiar with the needed commands by now: 

git add po 

git commit -a -m "Add POT file" 

git push 

Next we need to give the user "pootle" commit authority to our Git project. Go to 
git. sugarlab s. org, sign in, and find your Project page and click on the mainline link. 
You should see this on the page that takes you to: 
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Project: Make Your Own Sugar Activities Book 
Examples 

Maintained jdsimmors 
Created: 03 Jan 21:46 

Clone repository 
Request merge 
Add committer 



Committers 

jdsimmons (owner) 



Qick on the Add committer link and type in the name pootle in the form that takes 
you to. When you come back to this page pootle will be listed under Committers. 

Your next step is to go to web site http: //bugs. sugarlab s. org and register for a user id. 
When you get that open up a ticket something like this: 
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sugarlabs 



lagged 



Create New Ticket 



Properties 

Summary: 
Description: 

Type: 

Milestone: 

Version: 

Keywords: 

DistributiorVos: 

Assign to: 


Add project "Make Youi Own Sugar Activities Book Examples" lo Pootle 

B / A * B]— f - B 




Diet pootle is alr**dy a committer for this project in Git. 








taBk t| Priority: | Unspecified by Mainfainar t| 






Unspecified by Release Team ▼] Component: 1 localization ▼] 






Unspecified -J Severity: | Unspecified^ 

Cc: 




Unspecilied ^\ Bug Status: |New _J 





The Component entry localization should be used, along with Type task. 

Believe it or not, this is all you need to do to get your Activity set up to be translated. 

Pay No Attention To That Man Behind The Curtain 

After this you'll need to do a few things to get translations from Pootle into your 
Activity. 

• When you add text strings (labels, error messages, etc.) to your Activity always use 
the _() function with them so they can be translated. 

• After adding new strings always run ./setup.py genpot to recreate the POT file. 

• After that commit and push your changes to Gitorious. 

• Every so often, and especially before releasing a new version, do a git pull. If 
there are any localization files added to Gitorious this will bring them to you. 

• After getting a bunch of new files run ./setup.py fix manifest to get the new files 
included in your MANIFEST file. Afterwards edit the MANIFEST with gedit to 
remove any unwanted entries (which will be Eric project files, etc.). 
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Localization with Pootle will create a large number of files in your project, some in the 
po directory and others in a new directory called locale. As long as these are listed in 
the MANIFEST they will be included in the .xo file that you will use to distribute your 
Activity. 

C'est Magnifique! 

Here is a screen shot of the French language version of Read Etexts reading Jules 
Verne's novel Le tour du monde en quatre-vingts jours: 



O ©•H it u 



<><><><><><><><><><><><><><><><><><><><><><><><><><! 



LETOUADU MONDE 
EN 

QUATRE-VINGTS JOURS 



par Jules Verne 



I 



DANS LEQUEL PHI LEAS FOGG ET PASSEPAFTOUT 
S'ACCEPTENT RECIPROQUEMENT L'UN COM ME HAITRE, 

L'AUTRE COM ME D0ME5TIQUE 

En I'annee 1B72, la maison portant le numero 7 de Saville-row, Burlington Gardens 
-- maison dans laquelle Bheridan mourut en 1S14 — , etait habitee par Phileas Fogg, 
esq.. Tun des membres les plus singuliers et les plus remarques du Reform-Club de 
Londres, bien qu'il semblat prendre a fcache de re rien faire qui put attirer 
I'attention. 



There is reason to believe that the book is in French too. 
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A 3 • Distribute Your Activity 

Choose A License 

Before you give your Activity to anyone you need to choose a license that it will be 
distributed under. Buying software is like buying a book. There are certain rights you 
have with a book and others you don't have. If you buy a copy of The DaVinci Code 
you have the right to read it, to loan it out, to sell it to a used bookstore, or to burn it. 
You do not have the right to make copies of it or to make a movie out of it. Software is 
the same way, but often worse. Those long license agreements we routinely accept by 
clicking a button might not allow you to sell the software when you're done with it, or 
even give it away. If you sell your computer you may find that the software you 
bought is only good for that computer, and only while you are the owner of the 
computer. (You can get good deals on reconditioned computers with no operating 
system installed for that very reason). 

If you are in the business of selling software you might have to hire a lawyer to draw up 
a license agreement, but if you're giving away software there are several standard 
licenses you can choose from for free. The most popular by far is called the General 
Public License, or GPL. Like the licenses Microsoft uses it allows the people who get 
your program to do some things with it but not others. What makes it interesting is not 
what it allows them to do (which is pretty much anything they like) but what it forbids 
them to do. 

If someone distributes a program licensed under the GPL they are also required to 
make the source code of the program available to anyone who wants it. That person 
may do as he likes with the code, with one important restriction: if he distributes a 
program based on that code he must also license that code using the GPL. This makes it 
impossible for someone to take a GPL licensed work, improve it, and sell it to someone 
without giving him the source code to the new version. 

While the GPL is not the only license available for Activities to be distributed on 
http : //activities . sugarlab s . org all the licenses require that anyone getting the Activity 
also gets the complete source code for it. You've already taken care of that requirement 
by putting your source code in Gitorious. If you used any code from an existing 
Activity licensed with the GPL you must license your own code the same way. If you 
used a significant amount of code from this book (which is also GPL licensed) you may 
be required to use the GPL too. 
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Is licensing something you should worry about? Not really. The only reason you'd 
want to use a license other than the GPL is if you wanted to sell your Activity instead of 
give it away. Consider what you'd have to do to make that possible: 

• You'd have to use some language other than Python so you could give someone 
the program without giving them the source code. 

• You would have to have your own source code repository not available to the 
general public and make arrangements to have the data backed up regularly. 

• You would have to have your own website to distribute the Activity. The website 
would have to be set up to accept payments somehow. 

• You would have to advertise this website somehow or nobody would know your 
Activity existed. 

• You would have to have a lawyer draw up a license for your Activity. 

• You would have to come up with some mechanism to keep your customers from 
giving away copies of your Activity. 

• You would have to create an Activity so astoundingly clever that nobody else could 
make something similar and give it away. 

• You would have to deal with the fact that your "customers" would be children with 
no money or credit cards. 

In summary, activities . sugarlab s . org is not the iPhone App Store. It is a place where 
programmers share and build upon each other's work and give the results to children 
for free. The GPL encourages that to happen, and I recommend that you choose that 
for your license. 

Add License Comments To Your Python Code 

At the top of each Python source file in your project (except setup.py, which is already 
commented) put comments like this: 



# filename Program description 
# 

# Copyright (C) 2010 Your Name Here 
# 

# This program is free software; you can redistribute it 

# and/or modify it under the terms of the GNU General 

# Public License as published by the Free Software 

# Foundation; either version 2 of the License, or 

# (at your option) any later version. 
# 

# This program is distributed in the hope that it will 

# be useful, but WITHOUT ANY WARRANTY; without even 

# the implied warranty of MERCHANTABILITY or FITNESS FOR 

# A PARTICULAR PURPOSE. See the GNU General Public 
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# License for more details . 
# 

# You should have received a copy of the GNU General 

# Public License along with this program; if not, write 

# to the Free Software Foundation, Inc., 51 Franklin 

# St, Fifth Floor, Boston, MA 02110-1301 USA 

If the code is based on someone else's code you should mention that as a courtesy. 

Create An .xo File 

Make certain that activity.info has the version number you want to give your Activity 
(currently it must be a positive integer) and run this command: 

. /setup. py dist_xo 

This will create a dist directory if one does not exist and put a file named something like 
ReadETextsII-l.xo in it. The "1" indicates version 1 of the Activity. 

If you did everything right this .xo file should be ready to distribute. You can copy it to 
a thumb drive and install it on an XO laptop or onto another thumb drive running 
Sugar on a Stick. You probably should do that before distributing it any further. I like 
to live with new versions of my Activities for a week or so before putting them on 
activities . sugarlab s , org. 

Now would be a good time to add dist to your .gitignore file, then commit it and push 
it to Gitorious. You don't want to have copies of your .xo files in Git. Another good 
thing to do at this point would be to tag your Git repository with the version number so 
you can identify which code goes with which version. 

git tag -m "Release 1" vl HEAD 
git push --tags 

Add Your Activity To ASLO 

When you're ready to post the .xo file on ASLO you'll create an account as you did with 
the other websites. When you've logged in there you'll see a Tools link in the upper 
right corner of the page. Click on that and you'll see a popup menu with an option for 
Developer Hub, which you should click on. That will take you to the pages where you 
can add new Activities. The first thing it asks for when setting up a new Activity is 
what license you will use. After that you should have no problem getting your Activity 
set up. 
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You will need to create an Activity icon as a .gif file and create screen shots of your 
Activity in action. You can do both of these things with The GIMP (GNU Image 
Manipulation Program). For the icon all you need to do is open the .svg file with The 
GIMP and Save As a .gif file. 

For the screen shots use sugar-emulator to display your Activity in action, then use the 
Screenshot option from the Create submenu of the File menu with these options: 



Screenshot 



Area 

® Take a screenshot of a single window 
Include window decoration 
Take a screenshot of the entire screen 
□ Include mouse pointer 
Select a region to grab 
Delay 

seconds 



10 



At the end of the delay, click in a window to snap it. 



.Help 



l Cancel 



| Snap 



This tells GIMP to wait 10 seconds, then take a screenshot of the window you click on 
with the mouse. You'll know that the 10 seconds are up because the mouse pointer will 
change shape to a plus (+) sign. You also tell it not to include the window decoration 
(which means the window title bar and border). Since windows in Sugar do not have 
decorations eliminating the decorations used by sugar-emulator will give you a 
screenshot that looks exactly like a Sugar Activity in action. 

Every Activity needs one screenshot, but you can have more if you like. Screenshots 
help sell the Activity and instruct those who will use it on what the Activity can do. 
Unfortunately, ASLO cannot display pictures in a predictable sequence, so it is not 
suited to displaying steps to perform. 

Another thing you'll need to provide is a home page for your Activity. The one for 
Read Etexts is here: 

http : //wiki. sugarlab s . org/go/Activities/Read E texts 
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Yes, one more website to get an account for. Once you do you can specify a link with 
I gol Activities! some_name and when you click on that link the Wiki will create a page for 
you. The software used for the Wiki is MediaWiki, the same as used for Wikipedia. 
Your page does not need to be as elaborate as mine is, but you definitely should provide 
a link to your source code in Gitorious. 
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A 4. Debugging Sugar Activities 

Introduction 

No matter how careful you are it is reasonably likely that your Activity will not work 
perfectly the first time you try it out. Debugging a Sugar Activity is a bit different than 
debugging a standalone program. When you test a standalone program you just run 
the program itself. If there are syntax errors in the code you'll see the error messages on 
the console right away, and if you're running under the Eric IDE the offending line of 
code will be selected in the editor so you can correct it and keep going. 

With Sugar it's a bit different. It's the Sugar environment, not Eric, that runs your 
program. If there are syntax errors in your code you won't see them right away. 
Instead, the blinking Activity icon you see when your Activity starts up will just keep 
on blinking for several minutes and then will just go away, and your Activity won't start 
up. The only way you'll see the error that caused the problem will be to use the Log 
Activity. If your program has no syntax errors but does have logic errors you won't be 
able to step through your code with a debugger to find them. Instead, you'll need to 
use some kind of logging to trace through what's happening in your code, and again use 
the Log Activity to view the trace messages. Now would be a good time to repeat some 
advice I gave before: 

Make A Standalone Version Of Your Program First 

Whatever your Activity does, it's a good bet that 80% of it could be done by a 
standalone program which would be much less tedious to debug. If you can think of a 
way to make your Activity runnable as either an Activity or a standalone Python 
program then by all means do it. 

Use PyLint, PyChecker, or PyFlakes 

One of the advantages of a compiled language like C over an interpreted language like 
Python is that the compiler does a complete syntax check of the code before converting 
it to machine language. If there are syntax errors the compiler gives you informative 
error messages and stops the compile. There is a utility call lint which C programmers 
can use to do even more thorough checks than the compiler would do and find 
questionable things going on in the code. 
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Python does not have a compiler but it does have several lint-like utilities you can run 
on your code before you test it. These utilities are pyflakes, pychecker, and pylint. 
Any Linux distribution should have all three available. 

PyFlakes 

Here is an example of using PyFlakes: 
pyflakes minichat.py 



minichat.py:25 
minichat.py:28 
minichat.py:29 
minichat.py:29 



'COLOR_BUTTON_GREY' imported but unused 
'XoColor' imported but unused 
'Palette' imported but unused 
' Canvaslnvoker ' imported but unused 



PyFlakes seems to do the least checking of the three, but it does find errors like these 
above that a human eye would miss. 

PyChecker 

Here is PyChecker in action: 

pychecker ReadEtextsActivity .py 

Processing ReadEtextsActivity... 

/usr/lib/python2 . 5/site-packages/dbus/_dbus .py : 251 : 
DeprecationWarning : The dbus_bindings module is not public 
API and will go away soon. 

Most uses of dbus_bindings are applications catching 
the exception dbus . dbus_bindings . DBusException . 
You should use dbus . DBusException instead (this is 
compatible with all dbus-python versions since 0.40.2) . 

If you need additional public API, please contact 
the maintainers via <dbus@lists . f reedesktop . org> . 

import dbus . dbus_bindings as m 

Warnings . . . 

/usr/lib/python2 . 5/site -packages /sugar/act ivity/activity.py: 84 7 

Parameter (ps) not used 

/usr/lib/python2 . 5/site -package s/sugar/activity/activity.py: 9 92 

Parameter (event) not used 

/usr/lib/python2 . 5/site -package s/sugar/activity/activity.py: 9 92 

Parameter (widget) not used 

/usr/lib/python2 . 5/site -package s/sugar/activity/activity.py: 996 

Parameter (widget) not used 

/usr/lib/python2 . 5/site-packages/sugar/graphics /window. py: 157 : 

No class attribute (_alert) found 

/usr/lib/python2 . 5/site-packages/sugar/graphics /window. py: 164 : 

Parameter (window) not used 

/usr/lib/python2 . 5/site-packages/sugar/graphics /window . py : 188 : 

Parameter (widget) not used 
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/usr/lib/python2. 5/ site-packages /sugar/graphics /window. py: 2 00: 
Parameter (event) not used 

/usr/lib/python2. 5/ site-packages /sugar/graphics /window. py: 2 00: 
Parameter (widget) not used 

ReadEtextsActivity . py : 62 : Parameter (widget) not used 

4 errors suppressed, use -#/--limit to increase the number 
of errors displayed 

PyChecker not only checks your code, it checks the code you import, including Sugar 
code. 



PyLint 

Here is PyLint, the most thorough of the three: 

pylint ReadEtextsActivity .py 

No config file found, using default configuration 
Module ReadEtextsActivity 



"*■"*■"*■"*■"*■"*■"*■"*■"*■"*■"*■-*■■*■ 



c 


177 : 


c 


1 : 


c 


27 : 



Line too long (96/80) 

Missing docstring 

Operator not preceded by a space 



page=0 

C: 27 : 
( ( [A-Z 
C: 30: 
C: 174 : 

match 
W: 30 : 
in cla 



30: 
33: 
62: 



Too ma 
C: 88: 
W: 89 : 
Using 
C: 90: 
Operat 



Invalid name "page" (should match 

_] [A-Z0-9J *) | ( .* ) ) $) 

ReadEtextsActivity: Missing docstring 

ReadEtextsActivity . read_file : Invalid name "zf" (should 
[a-z_] [a-z0-9_] {2,30}$)~ 

ReadEtextsActivity: Method 'write_file' is abstract 
ss 'Activity' but is not overridden 
ReadEtextsActivity: Too many ancestors (12/7) 

ReadEtextsActivity. init : Using the global statement 

ReadEtextsActivity. keypress_cb: 
ny return statements (7/6) 
ReadEtextsActivity. page_previous : 
ReadEtextsActivity. page_previous : 
the global statement 
ReadEtextsActivity. page_previous : 
or not preceded by a space 
page=page-l 



Missing docstring 



C: 91: ReadEtextsActivity. page_previous : 
Operator not preceded by a space 
if page < 0: page=0 

C: 91 : ReadEtextsActivity . page_previous : More than one 

statement on a single line 

C: 96 : ReadEtextsActivity . page next : Missing docstring 

W: 97 : ReadEtextsActivity . page_next : Using the global 

statement 

C: 98 : ReadEtextsActivity . page_next : Operator not preceded 

by a space 

page=page+l 
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C: 99 : ReadEtextsActivity .pagenext : More than one 

statement on a single line 

C : 104 : ReadEtextsActivity . font_decrease : Missing docstring 

C : 112 : ReadEtextsActivity . font_increase : Missing docstring 

C : 118 : ReadEtextsActivity . scroll_down : Missing docstring 

C : 130 : ReadEtextsActivity . scroll_up : Missing docstring 

C : 142 : ReadEtextsActivity . show_page : Missing docstring 

W : 143 : ReadEtextsActivity . show_page : Using global for 

'PAGE_SIZE' but no assigment is done 

W : 143 : ReadEtextsActivity . show_page : Using global for 

' current_word ' but no assigment is done 

W: 157 : ReadEtextsActivity. save_extracted_f ile : Redefining 

name 'zipfile' from outer scope (line 21) 

C:163: ReadEtextsActivity. save_extracted_f ile : Invalid 

name "f" (should match [a-z_] Ta-z0-9_] { 2 , 30 } $ ) 

W : 171 : ReadEtextsActivity . readf ile : Using global 

for 'PAGE_SIZE' but no assigment is done 

C : 177 : ReadEtextsActivity . readf ile : Invalid name 

"currentFileName" (should match [a-z_] [a-z0-9_] { 2 , 30 } S ) 

C : 17 9 : ReadEtextsActivity . readf ile : Invalid name 

"currentFileName" (should match [a-z_] [a-z0-9_] { 2 , 30 } $ ) 

C : 197 : ReadEtextsActivity . make_new_f ilename : Missing 

docstring 

R : 1 97 : ReadEtextsActivity .make_new_f ilename : Method could be 

a function 

R: 30 : ReadEtextsActivity : Too many public methods (350/20) 

W: 174 : ReadEtextsActivity. readf ile : Attribute 

'zf' defined outside init 

W: 181 : ReadEtextsActivity. readf ile : Attribute 

'etext_file' defined outside init 

W: 175: ReadEtextsActivity. readf ile : Attribute 

'book_files' defined outside init 

W: 182 : ReadEtextsActivity. readf ile : Attribute 
'page_index' defined outside init 

... A bunch of tables appear here . . . 

Global evaluation 

Your code has been rated at 7.52/10 (previous run: 7.52/10) 

PyLint is the toughest on your code and your ego. It not only tells you about syntax 
errors, it tells you everything someone might find fault with in your code. This includes 
style issues that won't affect how your code runs but will affect how readable it is to 
other programmers. 
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The Log Activity 

When you start testing your Activities the Log Activity will be like your second home. ! 
It displays a list of log files in the left pane and when you select one it will display the 
contents of the file in the right pane. Every time you run your Activity a new log file is 
created for it, so you can compare the log you got this time with what you got on 
previous runs. The Edit toolbar is especially useful. It contains a button to show the 
log file with lines wrapped (which is not turned on by default but probably should be). 
It has another button to copy selections from the log to the clipboard, which will be 
handy if you want to show log messages to other developers. 

The Tools toolbar has a button to delete log files. I've never found a reason to use it. 
Log files go away on their own when you shut down sugar-emulator. 




datastore.log 

ret. flossmamjals. Minichat-l.log 

org.laotop.Log-l.lrjrj 

presenceservice.log 

sheil.log 

telepathy-: alut .log 

booUag 

booUog-20100122 
boot. log- 2 Ql cio 124 

fcorjt.log-20100206 

tOOt.log-20100215 

drnesg 

dmesg.cld 

lasting 



HUbHU pjJKy iBuuuy uujctL dl UXdiULUW I l>Uyai f|.,- ciT ii.. c 

buddy+Buddy at fea566c58]> 

1266714541.986980 DEBUS root: Activity. write_file is not 
implemented. 

12667 1454 L 99736 L DEBUG root: data store, write 
12667 1454 1. 999744 DEBUS root: dbu sjielpers. update : Ldb7f629- 

d202 - 409f - 923e - Qc 1258925027, /h ome/j in/ . su ga r/def au It/ 

data/ ldb7f 629 - d2Q2- 4Q9f - 923e- oc 1 2QB92Qb27. doc , {dbu s. string 
u 'activity _id ' ) : dbus.ByteArray 
I '4c222799748a56b24e8e29c7dBc585f6Be9f512c ' , 

vafiant_level=i) , dbus.Stringlu 'title_set_by_user' ) : 
dbus.ByteArray ( 'B' , variant_level=l] , dbus.String(u 'uid' ] : 
dbu 5 . ByteA rray [ ' idb7f 629 - d2B2 - 4B9f - 923e - Be 12B892Bb27 ' , 
vanant_level=l] , dbus.Stringlu 'title' ) : dbu s . ByteA r ray 
{'Mini Chat Activity, variant_level=L), dbu &. String 
(u 'timestamp' ): 1266714541, dbu s. St ring (u' activity ) : 
dbu s. ByteA rray [ 'net.flossmanuals.MiniChat', 
vanant_level=l] , dbu 5, St ring lu 'share- scope' ) : 
|dbus. ByteA rray ('public, variant_level=l) , dbus. string 
[u'keep'): dbu s . ByteA r ray [ 'fl' , variant_level=l) , dbus. String 
fu 'icon-color' J: dbus.ByteArrayl '#BBABFF,#FF2B34' , 
|vanant_level=l] , dbus.Stringlu 'mtime' ] : 
■281fl-82-2LTaUa9:8L. 999242*. dbu 6. St ring (u 'preview' ) : 
'omitted;-', dbus.string(u'miire_type') : dbu s. ByteA rray 
I 'text;' plain ' , variant_level=L] >, True 
1266714542,046518 DEBUS root: Written object Idb7f629- 
|d2S2-459f-923e-5cl2B392Bb27 to the datastore. 
1266714542. 117447 DEBUG root: Activity. _save_cb 



Here is what the Log Activity looks like showing a syntax error in your code: 
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T" /tiorne/jim/.sugarAJefault/logs 
4a Castors Jog 
net , flossrnanu als .Mini ch« 
ci»j Jap Lop Analyze -l.log 
org.la.pcop-Log-l.log 
4Kj.laptop.Log-2.loa. 
presenceservice.log 
shell.log 
telepathy-salut.log 



A]sr/lib/python2.6/site-paekages/sugar/util.py:25: 
DeprecationWaming: the sha nodule is deprecated; use the hashlib 
nodule instead 

inport sha 
Traceback (most recent call last): 

File vusr/bin/sugar- activity, line 21, in -aTodule* 

main .main () 
Fa le " /u 5 r/ lib/py thon 2 . 6/ si te - pac kage 5/ su ga r/ac tivi ty/main , py " , 
line 112, in main 

module = inport (modulejname) 

File Vu sr/share/sugar/activities/Speak. activity/activity, py 1 ', 
line 59, in <module> 
import voice 
File "/usr/sha re/ sugar/activities/speak, activity/voice. py", line 
104 

as = re. split ( r" ['a-z]+', a. lower!)) 



v(j, lux. olpc.speak-l.log 
v /uac/iog 

bootlog 

tOOtJog- 20100122 
b00t.bg- 20100124 
bOTt-log-20100206 
bOOt.log-20100215 




^^yntaxErrar: invalid syntax 
IRl266716031, 992572 DEBUS root; 



_c leanu p_tenc_f i le 5 



Logging 

Without a doubt the oldest debugging technique there is would be the simple print 
statement. If you have a running program that misbehaves because of logic errors and 
you can't step through the code in a debugger to figure out what's happening you might 
print statements in your code. For instance, if you aren't sure that a method is ever 
getting executed you might put a statement like this as the first line of the method: 

def my_method() : 

print 'my_method () begins' 

You can include data in your print statements too. Suppose you need to know how 
many times a loop is run. You could do this: 

while linecount < PAGE_SIZE: 

line = self . etext_f ile . readline ( ) 
label_text = label_text + Unicode (line, 

■ iso-8859-1' ) 
linecount = linecount + 1 
print ' linecount=' , linecount 

The output of these print statements can be seen in the Log Activity. When you're 
finished debugging your program you would remove these statements. 



96 



An old programming book I read once made the case for leaving the statements in the 
finished program. The authors felt that using these statements for debugging and them 
removing them is a bit like wearing a parachute when the plane is on the ground and 
taking it off when it's airborne. If the program is out in the world and has problems you 
might well wish you had those statements in the code so you could help the user and 
yourself figure out what's going on. On the other hand, print statements aren't free. 
They do take time to run and they fill up the log files with junk. What we need are 
print statements that you can turn on an off. 

The way you can do this is with Python Standard Logging. In the form used by most 
Activities it looks like this: 

self._logger = logging . getLogger ( 
' read-etexts-activity ' ) 

These statements would go in the init () method of your Activity. Every time you 

want to do a print() statement you would do this instead: 

def _shared_cb ( self , activity): 

self ._logger . debug ( 'My activity was shared') 

self . initiating = True 
self ._sharing_setup ( ) 

self ._logger . debug ( 

'This is my activity: making a tube. . . ') 

id = self .tubes_chan [telepathy. CHANNEL_TYPE_TUBES] . \ 
Of ferDBusTube (SERVICE, {}) 

def _sharing_setup ( self ) : 

if self ._shared_activity is None: 
self ._logger . error ( 

'Failed to share or join activity') 

return 

Notice that there are two kinds of logging going on here: debug and error. These are 
error levels. Every statement has one, and they control which log statements are run 
and which are ignored. There are several levels of error logging, from lowest severity to 
highest: 

self . _logger . debug ( "debug message" ) 

self. _logger. info ("info message" ) 

self. _logger. warn ("warn message" ) 

self. _logger. error ("error message" ) 

self. _logger. critical ("critical message" ) 

When you set the error level in your program to one of these values you get messages 
with that level and higher. You can set the level in your program code like this: 

self. _logger.setLevel( logging. DEBUG) 
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You can also set the logging level outside your program code using an environment 
variable. For instance, in Sugar .82 and lower you can start sugar-emulator like this: 

SUGAR_LOGGER_LEVEL=debug sugar-emulator 

The way you accomplish the same thing in Sugar .84 and greater is to edit the file 
~/.sugar/debug and uncomment the line that sets the SUGARLOGGERLEVEL. 

The Analyze Activity 

Another Activity you may find yourself using at some point is Analyze. This is more 
likely to be used to debug Sugar itself than to debug your Activity. If, for instance, your 
collaboration test environment doesn't seem to be working this Activity might help you 
or someone else figure out why. 

I don't have a lot to say about this Activity here, but you should be aware that it exists. 




INFO 
INFO 
INFO 
INFO 
INFO 
INFO 



...II 



Activity jorg/laptop/sugar;presencejActivitieyi emitted Newchlannel( , ..7Muccbanne^l■) or mentioned the cb^ 
Activity /org/]aptop/SLigarVPresence./ActivitJe^i emitted JJewCliannei[".../Muc"ILibe£Channell") or mentioned tt 
Activity jarg/laptopsugar/Presence/Activitieyi emitted Buddyjoined(".../lseyidf7dbce<}7d43a5b5C48e50f3358s' 
< Buddy /org/laptopysugary Presence/Buddi es^ceyidyTdbc e B7 d43 a5b 504Be5 □ f33 5SE5B22?2B99c 9e7 1 >.Get Prope 
Bu ddy /Qfg/lap topysugar/Pne&enc e/Buddies/keyi d/7 d b c eo 7d43a 5b5Q4Be 50f335BB5B 2 2 2 2B 9 E c 9e T 7 emitt ed Acti 
Bu ddy /org /I ap topjsugar/Pnesenc e/Buddies/keyi dy7-db c eo 7d43a 5b504Be 5Cf335BB5B 2 2 2 2B g 3 c 9e 7 7 emitt ed Tele 

Activities; 

4c222799748a56b24e8e29c7dOc585f60a9f512c #FF2E34 r #00A0FF net.flossmanjals.MmiChat Mm 



Buddies: 



Object path 



.Jl<eyidv7dbce<)7d43a5b5048e50f33588582222899c9e77 580 bytes, shal 7dbce07d43a5b5u48e50f33538532222399 
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-L 3 • Making Shared Activities 

Introduction 

One of the distinctive features of Sugar is how many Activities support being used by 
more than one person at a time. More and more computers are being used as a 
communications medium. The latest computer games don't just pit the player against 
the computer; they create a world where players compete against each other. Websites 
like Facebook are increasingly popular because they allow people to interact with each 
other and even play games. It is only natural that educational software should support 
these kinds of interactions. 

I have a niece that is an enthusiastic member of the Club Penguin website created by 
Disney. When I gave her Sugar on a Stick Blueberry as an extra Christmas gift I 
demonstrated the Neighborhood view and told her that Sugar would make her whole 
computer like Club Penguin. She thought that was a pretty cool idea. I felt pretty cool 
saying it. 

Running Sugar As More Than One User 

Before you write any piece of software you need to give some thought to how you will 
test it. In the case of a shared Activity you might think you'd need more than one 
computer available to do testing, but those who designed Sugar did give some thought 
to testing shared Activities and gave us ways to test them using only one computer. 
These methods have been evolving so there are slight variations in how you test 
depending on the version of Sugar you're using. The first thing you have to know is 
how to run multiple copies of Sugar as different users. 

Fedora 10 (Sugar .82) 

In Sugar .82 there is a handy way to run multiple copies of sugar-emulator and have 
each copy be a different user, without having to be logged into your Linux box as more 
than one user. On the command line for each additional user you want add a 
SUGARPROFILE environment variable like this: 

SUGAR_PROFILE=austen sugar-emulator 
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When you do this sugar-emulator will create a directory named austen under -/.sugar to 
store profile information, etc. You will be prompted to enter a name and select colors 
for your icon. Every time you launch using the SUGARPROFILE of austen you will 
be this user. If you launch with no SUGARPROFILE you will be the regular user you 
set up before. 

Fedora 11 (Sugar .84) 

As handy as using SUGARPROFILE is the developers of Sugar decided it had 
limitations so with version .84 and later it no longer works. With .84 and later you need 
to create a second Linux user and run your sugar-emulators as two separate Linux 
users. In the GNOME environment there is an option Users and Groups in the 
Administration submenu of the System menu which will enable you to set up a 
second user. B efore it comes up it will prompt you for the administrative password you 
created when you first set up Linux. 

Creating the second user is simple enough, but how do you go about being logged in as 
two different users at the same time? It's actually pretty simple. You need to open a 
terminal window and type this: 

ssh -XY jaustenSlocalhost 

where "jausten" is the userid of the second user. You will be asked to verify that the 
computer at "localhost" should be trusted. Since "localhost" just means that you are 
using the network to connect to another account on the same computer it is safe to 
answer "yes". Then you will be prompted to enter her password, and from then on 
everything you do in that terminal window will be done as her. You can launch sugar- 
emulator from that terminal and the first time you do it will prompt you for a name and 
icon colors. 

sugar-jhbuild 

With sugar-jhbuild (the latest version of Sugar) things are a bit different again. You will 
use the method of logging in as multiple Linux users like you did in .84, but you won't 
get prompted for a name. Instead the name associated with the userid you're running 
under will be the name you'll use in Sugar. You won't be able to change it, but you will 
be able to choose your icon colors as before. 

You will need a separate install of sugar-jhbuild for each user. These additional installs 
will go quickly because you installed all the dependencies the first time. 
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Connecting To Other Users 

Sugar uses software called Telepathy that implements an instant messaging protocol 
called XMPP (Extended Messaging and Presence Protocol). This protocol used to be 
called Jabber. In essence Telepathy lets you put an instant messaging client in your 
Activity. You can use this to send messages from user to user, execute methods 
remotely, and do file transfers. 

There are actually two ways that Sugar users can join together in a network: 

Salut 

If two computer users are connected to the same segment of a network they should be 
able to find each other and share Activities. If you have a home network where 
everyone uses the same router you can share with others on that network. This is 
sometimes called Link-Local XMPP. The Telepathy software that makes this possible is 
called Salut. 

The XO laptop has special hardware and software to support Mesh Networking, where 
XO laptops that are near each other can automatically start networking with each other 
without needing a router. As far as Sugar is concerned, it doesn't matter what kind of 
network you have. Wired or wireless, Mesh or not, they all work. 

Jabber Server 

The other way to connect to other users is by going through a Jabber Server. The 
advantage of using a Jabber server is you can contact and share Activities with people 
outside your own network. These people might even be on the other side of the world. 
Jabber allows Activities in different networks to connect when both networks are 
protected by firewalls. The part of Telepathy that works with a Jabber server is called 
Gabble. 

Generally you should use Salut for testing if at all possible. This simplifies testing and 
doesn't use up resources on a Jabber server. 

It does not matter if your Activity connects to others using Gabble or Salut. In fact, the 
Activity has no idea which it is using. Those details are hidden from the Activity by 
Telepathy. Any Activity that works with Salut will work with Gabble and vice versa. 

To set up sugar-emulator to use Salut go to the Sugar control panel: 
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In Sugar .82 this menu option is Control Panel. In later versions it is My Settings. 
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Qick on the Network icon. 
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Wireless 



Turn off the wireless radio to save battery life 

Radio 

Discard network history if you have 
trouble connecting to the network 



Discard network history 



Mesh 



Server: 






I 






The Server field in this screen should be empty to use Salut. You can use the 
backspace key to remove any entry there. 

You will need to follow these steps for every Sugar user that will take part in your test. 

If for some reason you wish to test your Activity using a Jabber server the OLPC Wiki 
maintains a list of publicly available servers at 
http://wiki.laptop.org/go/Community Jabber Servers . 

Once you have either Salut or a Jabber server set up in both instances of Sugar that you 
are running you should look at the Neighborhood view of both to see if they can detect 
each other, and perhaps try out the Chat Activity between the two. If you have that 
working you're ready to try programming a shared Activity. 

The MiniChat Activity 

Just as we took the Read Etexts Activity and stripped it down to the basics we're going 
to do the same to the Chat Activity to create a new Activity called MiniChat. The real 
Chat Activity has a number of features that we don't need to demonstrate shared 
Activity messaging: 
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• It has the ability to load its source code into Pippy for viewing. This was a feature 
that all Activities on the XO were supposed to have, but Chat is one of the few that 
implemented it. Personally, if I want to see an Activity's code I prefer to go to 
git.sugarlabs.org where I can see old versions of the code as well as the latest. 

• Chat can connect one to one with a conventional XMPP client. This may be useful 
for Chat but would not be needed or desirable for most shared Activities. 

• If you include a URL in a Chat message the user interface enables you to click on 
the URL make a Journal entry for that URL. You can then use the Journal to open 
it with the Browse Activity. (This is necessary because activities cannot launch 
each other). Pretty cool, but not needed to demonstrate how to make a shared 
Activity. 

• The chat session is stored in the Journal. When you resume a Chat entry from the 
Journal it restores the messages from your previous chat session into the user 
interface. We already know how to save things to the Journal and restore things 
from the Journal, so MiniChat won't do this. 

The resulting code is about half as long as the original. I made a few other changes too: 

• The text entry field is above the chat messages, instead of below. This makes it 
easier to do partial screenshots of the Activity in action. 

• I removed the new style toolbar and added an old style toolbar, so I could test it in 
Fedora 10 and 11 which don't support the new toolbars. 

• I took the class TextChannelWrapper and put it in its own file. I did this because 
the class looked like it might be useful for other projects. 

The code and all supporting files for MiniChat are in the MiniChat directory of the Git 
repository. You'll need to run 

. /setup . py dev 

on the project to make it ready to test. The activity.info looks like this: 

[Activity] 
name = Mini Chat 

service_name = net . flossmanuals .MiniChat 
icon = chat 

exec = sugar-activity minichat .MiniChat 
show_launcher = yes 
activity version = 1 
license = GPLv2+ 

Here is the code for textchannel.py: 

import logging 

from telepathy . client import Connection, Channel 
from telepathy . interfaces import ( 
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CHANNEL_INTERFACE, CHANNEL_INTERFACE_GROUP, 
CHANNEL_TYPE_TEXT, CONN_INTERFACE_ALIASING) 
from telepathy . constants import ( 

CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES, 
CHANNEL_TEXT_MESSAGE_TYPE_NORMAL) 

class TextChannelWrapper (ob j ect ) : 

"""Wrap a telepathy Text Channel to make 
usage simpler.""" 

def init (self, textchan, conn) : 

"""Connect to the text channel 

self ._activity_cb = None 

self ._activity_close_cb = None 

self ._text_chan = text_chan 

self ._conn = conn 

self._logger = logging . getLogger ( 

'minichat-activity. TextChannelWrapper ' ) 
self ._signal_matches = [] 

m = self ._text_chan [CHANNEL_INTERFACE] . \ 
connect_to_signal ( 
'Closed', self ._closed_cb) 
self . _signal_matches . append (m) 

def send(self, text): 

"""Send text over the Telepathy text channel.""" 
# XXX Implement CHANNEL_TEXT_MESSAGE_TYPE_ACTION 
if self ._text_chan is not None: 

self ._text_chan [CHANNEL_TYPE_TEXT] . Send ( 

CHANNEL_TEXT_MESSAGE_TYPE_NORMAL, text) 

def close ( self) : 

"""Close the text channel.""" 

self ._logger . debug (' Closing text channel') 

try : 

self ._text_chan [CHANNEL_INTERFACE] .Close () 
except : 

self . _logger . debug (' Channel disappeared ! ' ) 

self . _closed_cb ( ) 

def _closed_cb ( self ) : 

"""Clean up text channel. 

self ._logger . debug (' Text channel closed.') 
for match in self ._signal_matches : 

match . remove ( ) 
self ._signal_matches = [] 
self ._text_chan = None 

if self ._activity_close_cb is not None: 
self ._activity_close_cb ( ) 

def set_received_callback (self , callback): 

"""Connect the function callback to the signal. 

callback -- callback function taking buddy 

and text args 
ii ii ii 

if self ._text_chan is None: 

return 
self ._activity_cb = callback 
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m = self ._text_chan [CHANNEL_TYPE_TEXT] . \ 

connect_to_signal ( 

'Received', self ._received_cb) 
self . _signal_matches . append (m) 

def handle_pending_messages (self ) : 

"""Get pending messages and show them as 
received. " "" 

for id, timestamp, sender, type, flags, text \ 
in self ._text_chan [ 

CHANNEL_TYPE_TEXT] . ListPendingMessages ( 
False) : 

self ._received_cb (id, timestamp, sender, 
type, flags, text) 

def _received_cb (self , id, timestamp, sender, 
type, flags, text) : 
"""Handle received text from the text channel. 

Converts sender to a Buddy. 

Calls self ._activity_cb which is a callback 

to the activity. 
ii ii ii 

if self ._activity_cb : 

buddy = self ._get_buddy (sender ) 
self ._activity_cb (buddy, text) 
self . _text_chan [ 

CHANNEL_TYPE_TEXT] . 
AcknowledgePendingMessages ( [id] ) 
else : 

self . _logger . debug ( 

'Throwing received message on the floor' 

' since there is no callback connected. See 

' set_received_callback ' ) 

def set_closed_callback (self , callback): 

"""Connect a callback for when the text channel 
is closed. 

callback -- callback function taking no args 



self ._activity_close_cb = callback 

def _get_buddy (self , cs_handle): 

"""Get a Buddy from a (possibly channel-specific) 
handle. """ 

# XXX This will be made redundant once Presence 

# Service provides buddy resolution 

from sugar . presence import presenceservice 

# Get the Presence Service 

pservice = presenceservice . get_instance ( ) 

# Get the Telepathy Connection 
tp_name, tp_path = \ 

pservice. get_pref erred_connection ( ) 
conn = Connection (tpname, tp_path) 
group = self ._text_chan [CHANNEL_INTERFACE_GROUP] 
my_csh = group . GetSelf Handle ( ) 
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if my_csh == cs_handle: 

handle = conn . GetSelf Handle ( ) 
elif group . GetGroupFlags ( ) & \ 

CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES: 

handle = group . GetHandleOwners ( [cs_handle] ) [0] 
else : 

handle = cs_handle 

# XXX: deal with failure to get the handle owner 
assert handle != 

return pservice . get_buddy_by_telepathy_handle ( 
tp_name, tp_path, handle) 

Here is the code for minichat.py: 

from gettext import gettext as 

import hippo 

import gtk 

import pango 

import logging 

from sugar . activity . activity import (Activity, 

ActivityToolbox, SCOPE_PRIVATE) 
from sugar . graphics . alert import NotifyAlert 
from sugar . graphics . style import (Color, COLOR_BLACK, 

COLOR_WHITE, COLOR_BUTTON_GREY, FONT_BOLD, 

FONT_NORMAL) 
from sugar . graphics . roundbox import CanvasRoundBox 
from sugar . graphics . xocolor import XoColor 
from sugar . graphics . palette import Palette, Canvaslnvoker 

from textchannel import TextChannelWrapper 

logger = logging . getLogger (' minichat-activity ' ) 

class MiniChat (Activity) : 

def init (self, handle) : 

Activity. init (self, handle) 

root = self .make_root ( ) 
self . set_canvas (root) 
root . show_all ( ) 
self . entry . grab_focus () 

toolbox = ActivityToolbox (self ) 

activity_toolbar = toolbox . get_activity_toolbar ( ) 
activity_toolbar . keep .props . visible = False 
self . set_toolbox (toolbox) 
toolbox . show ( ) 

self. owner = self .pservice . get_owner ( ) 

# Auto vs manual scrolling: 
self ._scroll_auto = True 
self ._scroll_value = 0.0 

# Track last message, to combine several 

# messages: 

self ._last_msg = None 

self ._last_msg_sender = None 
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self . text_channel = None 

if self ._shared_activity : 

# we are joining the activity 
self.connect('joined', self ._j oined_cb) 
if self . get_shared ( ) : 

# we have already joined 
self . _j oined_cb ( ) 

else : 

# we are creating the activity 

if not self .metadata or self . metadata . get ( 
' share-scope ' , 
SCOPE_PRIVATE) == SCOPE_PRIVATE : 

# if we are in private session 
self ._alert (_( 'Off-line' ) , 

_( 'Share, or invite someone.')) 
self .connect ( 'shared' , self . _shared_cb) 

def _shared_cb (self , activity): 

logger . debug (' Chat was shared') 
self ._setup ( ) 

def _setup(self) : 

self . text_channel = TextChannelWrapper ( 

self . _shared_activity . telepathy_text_chan, 

self . _shared_activity . telepathy_conn) 
self . text_channel . set_received_callback ( 

self . _received_cb) 
self._alert(_( 'On-line') , _('Connected') ) 
self . _shared_activity . connect ( ' buddy- j oined ' , 

self . _buddy_j oined_cb) 
self . _shared_activity .connect ( 'buddy-left' , 

self . _buddy_lef t_cb) 
self. entry. setsensitive (True) 
self . entry . grab_focus () 

def _j oined_cb (self , activity): 

"""Joined a shared activity.""" 

if not self ._shared_activity : 
return 

logger . debug (' Joined a shared chat') 

for buddy in \ 

self . _shared_activity . get_j oined_buddies ( ) : 
self ._buddy_already_exists (buddy) 

self ._setup ( ) 

def _received_cb (self , buddy, text) : 

"""Show message that was received.""" 
if buddy: 

nick = buddy .props . nick 
else : 

nick = ' ??? ' 
logger . debug ( 

'Received message from %s: %s', nick, text) 
self . add_text (buddy, text) 

def _alert(self, title, text=None): 
alert = Notif yAlert (timeout=5 ) 
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alert . props . title = title 

alert . props .msg = text 

self . add_alert (alert) 

alert . connect ( ' response ' , self . _alert_cancel_cb) 

alert . show ( ) 

def _alert_cancel_cb (self , alert, response_id) : 
self . remove_alert (alert) 

def _buddy_j oined_cb (self, activity, buddy) : 
"""Show a buddy who joined""" 
if buddy == self. owner: 

return 
if buddy: 

nick = buddy . props . nick 
else : 

nick = ' ??? ' 
self . add_text (buddy, buddy .props . nick+ ' 

' +_ ( 'joined the chat'), 

statu s_message=True) 

def _buddy_lef t_cb (self, activity, buddy) : 
"""Show a buddy who joined""" 
if buddy == self. owner: 

return 
if buddy: 

nick = buddy . props . nick 
else : 

nick = ' ??? ' 
self . add_text (buddy, buddy .props . nick+ ' 

'+_( 'left the chat ' ) , 

statu s_message=True) 

def _buddy_already_exists (self , buddy): 

"""Show a buddy already in the chat.""" 
if buddy == self. owner: 

return 
if buddy: 

nick = buddy . props . nick 
else : 

nick = ' ??? ' 
self . add_text (buddy, buddy .props . nick+ 

' '+_( ' is here ' ) , 

statu s_message=True) 

def make_root ( self ) : 

conversation = hippo . CanvasBox ( 

spacing=0 , 

background_color=COLOR_WHITE . get_int ( ) ) 
self . conversation = conversation 

entry = gtk.EntryO 

entry. modi fyjog (gtk . STATE_INSENSITIVE, 

COLOR_WHITE . get_gdk_color ( ) ) 
entry. modi fyjoase (gtk . STATE_INSENSITIVE, 

COLOR_WHITE . get_gdk_color ( ) ) 
entry. set_sensitive (False) 
entry. connect ( 'activate' , 
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self . entry_activate_cb) 
self .entry = entry 

hbox = gtk.HBox () 
hbox. add (entry) 

sw = hippo . CanvasScrollbars ( ) 

sw. set_policy (hippo . ORIENTATION_HORIZONTAL, 

hippo . SCROLLBAR_NEVER) 
sw. set_root (conversation) 
self . scrolled_window = sw 

vadj = self . scrolled_window .props .widget . \ 

get_vadjustment () 
vadj .connect ( 'changed' , self .rescroll) 
vadj .connect ( 'value-changed' , 

self . scroll_value_changed_cb) 

canvas = hippo . Canvas ( ) 
canvas . set_root (sw) 

box = gtk . VBox (homogeneous=False) 
box . pack_start (hbox, expand=False) 
box . pack_start (canvas) 

return box 

def rescroll ( self , adj , scroll=None) : 

"""Scroll the chat window to the bottom""" 
if self ._scroll_auto : 

adj . set_value (adj . upper -adj . page_size) 
self ._scroll_value = adj . get_value ( ) 

def scroll_value_changed_cb (self , adj, scroll=None) : 
"""Turn auto scrolling on or off. 

If the user scrolled up, turn it off. 

If the user scrolled to the bottom, turn it back on. 
ii ii ii 

if adj . getvalue ( ) < self ._scroll_value : 

self ._scroll_auto = False 
elif adj . get_value ( ) == adj . upper-adj . page_size : 

self ._scroll_auto = True 

def add_text ( self , buddy, text, status_message=False) : 
"""Display text on screen, with name and colors. 

buddy -- buddy object 

text -- string, what the buddy said 

status_message -- boolean 

False: show what buddy said 

True: show what buddy did 

hippo layout: 

. rb . 

| +name_vbox+ + msg_vbox 1- 

II ' II "~ II 

| | nick: | | H msg_hbox 1- | 
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text 



-l msg hbox- 

I text 


- + 
1 







if b 



uddy 
nick 
colo 
try: 



= buddy . props . nick 
r = buddy . props . color 



\ 



# Sel 
coloi 



coloi 

c 

coloi 

if cc 



html = 
color : 



( 



color_stroke_html, color_f ill_html 

color . split ( ' , ' ) 
;pt ValueError: 

color_stroke_html, color_fill_ 

'#000000 T , '#888888'7 
:lect text color based on fill 
>r_f ill_rgba = Color ( 

color_f ill_html) .get_rgba() 
color_f ill_gray = (color_f ill_rgba [ ] + 

color_f ill_rgba [ 1 ] + 

color_f ill_rgba [ 2 ] ) /3 
>r_stroke = Color ( 

color_stroke_html) . get_int() 
>r fill = Color (color_f ill_html ) . get_int() 
iolor_f ill_gray < 0.5: 

text_color = COLOR_WHITE . get_int ( ) 



else : 



text_color = COLOR_BLACK . get_int ( ) 



else : 



nick = ' ??? ' 

# XXX: should be ' ' but leave for debugging 

color_stroke = COLOR_BLACK . get_int ( ) 

color_fill = COLOR_WHITE.get_int () 

text_color = COLOR_BLACK . get_int ( ) 

color = '#000000, #FFFFFF' 

# Check for Right-To-Left languages: 
if pango . f ind_base_dir (nick, -1) == \ 

pango . DIRECTION_RTL : 
lang_rtl = True 
else : 

lang_rtl = False 

# Check if new message box or add text to previous: 
new_msg = True 

if self ._last_msg_sender : 
if not status_message : 

if buddy == self ._last_msg_sender : 
# Add text to previous message 
new_msg = False 

if not new_msg: 

rb = self ._last_msg 

msg_vbox = rb . get_children ( ) [1] 

msg_hbox = hippo . CanvasBox ( 



113 



orient at ion=hippo . ORIENTATION_HORIZONTAL) 
msg_vbox . append (msg_hbox) 
else : 

rb = CanvasRoundBox ( 

background_color=color_f ill, 

border_color=color_stroke, 

padding=4 ) 
rb . props .border_color = color_stroke 
self ._last_msg = rb 
self ._last_msg_sender = buddy 
if not status message: 

name = hippo . CanvasText (text=nick+ ' : ', 
color=text_color , 
f ont_desc=FONT_BOLD . get_pango_desc ( ) ) 

name_vbox = hippo . CanvasBox ( 

orient at ion=hippo . ORIENTATION_VERTICAL) 

name_vbox . append (name) 

rb . append (name_vbox) 
msg_vbox = hippo . CanvasBox ( 

orientation=hippo.ORIENTATION_VERTICAL) 
rb . append (msg_vbox) 
msg_hbox = hippo . CanvasBox ( 

orient at ion=hippo . ORIENTATION_HORIZONTAL) 
msg_vbox . append (msg_hbox) 

if status_message : 

self .lastrasgsender = None 

if text: 

message = hippo . CanvasText ( 

text=text , 

s i z e_mode=hippo . CANVAS_S I ZE_WRAP_WORD , 

color=text_color , 

f ont_desc=FONT_NORMAL . get_pango_desc ( ) , 

xalign=hippo.ALIGNMENT_START) 
msg_hbox . append (message) 

# Order of boxes for RTL languages : 
if lang_rtl : 

msg_hbox . reverse ( ) 

if new_msg: 

rb . reverse ( ) 

if new_msg: 

box = hippo . CanvasBox (padding=2 ) 

box . append (rb) 

self. conversation. append (box) 

def entry_activate_cb (self , entry): 
text = entry .props . text 
logger . debug (' Entry : %s ' % text) 
if text: 

self . add_text (self . owner , text) 
entry . props . text = ' ' 
if self . text_channel : 

self. text_channel. send (text) 
else : 

logger . debug ( 
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'Tried to send message but text ' 
'channel not connected.') 



And this is what the Activity looks like in action: 



F 



Mini Chat Activity 




Jane Austen is here 



James: Hello Jane. 

How are you? 




Jane Austen: As well as can be expected. And you? 



Try launching more than one copy of sugar-emulator, with this Activity installed in 
each. If you're using Fedora 10 and SUGARPROFILE the Activity does not need to be 
installed more than once, but if you're using a later version of Sugar that requires 
separate Linux userids for each instance you'll need to maintain separate copies of the 
code for each user. In your own projects using a central Git repository at 
git.sugarlabs.org will make this easy. You just do a git push to copy your changes to 
the central repository and a git pull to copy them to your second userid. The second 
userid can use the public URL. There's no need to set up SSH for any user other than 
the primary one. 

You may have read somewhere that you can install an Activity on one machine and 
share that Activity with another that does not have the activity installed. In such a case 
the second machine would get a copy of the Activity from the first machine and install it 
automatically. You may have also read that if two users of a shared Activity have 
different versions of that Activity then the one who has the newer version will 
automatically update the older. Neither statement is true now or is likely to be true in 
the near future. These ideas are discussed on the mailing lists from time to time but 
there are practical difficulties to overcome before anything like that could work, mostly 
having to do with security. For now both users of a shared Activity must have the 
Activity installed. On the other hand, depending on how the Activity is written two 
different versions of an Activity may be able to communicate with one another. If the 
messages they exchange are in the same format there should be no problem. 
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Once you have both instances of sugar-emulator going you can launch MiniChat on one 
and invite the second user to Join the Chat session. You can do both with the 
Neighborhood panes of each instance. Making the invitation looks like this: 




Make friend 




Accepting it looks like this: 



Mini Chat Activity 



c* 



After you've played with MiniChat for awhile come back and we'll discuss the secrets 
of using Telepathy to create a shared Activity. 
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Know who Your Buddies Are 

XMPP, as we said before, is the Extended Messaging and Presence Protocol. ! 

Presence is just what it sounds like; it handles letting you know who is available to 
share your Activity, as well as what other Activities are available to share. There are 
two ways to share your Activity. The first one is when you change the Share with: 
pulldown on the standard toolbar so it reads My Neighborhood instead of Private. 
That means anyone on the network can share your Activity. The other way to share is 
to go to the Neighborhood view and invite someone specific to share. The person 
getting the invitation has no idea of the invitation was specifically for him or broadcast 
to the Neighborhood. The technical term for persons sharing your Activity is Buddies. 
The place where Buddies meet and collaborate is called an MUC or Multi User 
Chatroom. 

The code used by our Activity for inviting Buddies and joining the Activity as a Buddy 
is in the init method: 

if self ._shared_activity : 

# we are joining the activity 
self.connect('joined', self ._j oined_cb) 
if self . get_shared ( ) : 

# we have already joined 
self . _j oined_cb ( ) 

else : 

# we are creating the activity 

if not self .metadata or self .metadata . get ( 
' share-scope ' , 
SCOPE_PRIVATE) == SCOPE_PRIVATE : 

# if we are in private session 
self ._alert (_( 'Off-line* ) , 

_( 'Share, or invite someone.')) 
self .connect ( 'shared' , self . _shared_cb) 

def _shared_cb ( self , activity): 

logger . debug (' Chat was shared') 
self ._setup ( ) 

def _j oined_cb ( self , activity): 

"""Joined a shared activity.""" 
if not self ._shared_activity : 

return 
logger . debug (' Joined a shared chat') 
for buddy in \ 

self ._shared_activity . get_j oined_buddies () : 

self . _buddy_already_exists (buddy) 
self ._setup ( ) 

def _setup ( self ) : 

self . text_channel = TextChannelWrapper ( 

self . _shared_activity . telepathy_text_chan, 
self . _shared_activity . telepathy_conn) 
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self . text_channel . set_received_callback ( 

self ._received_cb) 
self._alert (_( 'On-line' ) , _( 'Connected' ) ) 
self . _shared_activity .connect ( 'buddy-joined' , 

self ._buddy_j oined_cb) 
self . _shared_activity .connect ( 'buddy-left' , 

self . _buddy_lef t_cb) 
self. entry. set_sensitive (True) 
self . entry . grab_focus () 

There are two ways to launch an Activity: as the first user of an Activity or by joining 
an existing Activity. The first line above in bold determines whether we are joining or 
are the first user of the Activity. If so we ask for the _joined_cb() method to be run when 
the 'joined' event occurs. This method gets a buddy list from the _shared_activity object 
and creates messages in the user interface informing the user that these buddies are 
already in the chat room. Then it runs the _setup() method. 

If we are not joining an existing Activity then we check to see if we are currently sharing 
the Activity with anyone. If we aren't we pop up a message telling the user to invite 
someone to chat. We also request that when the 'shared' even happens the _shared_cb() 
method should run. This method just runs the _setup() method. 

The _setup() method creates a TextChannelWrapper object using the code in 
textchannel.py. It also tells the _shared_activity object that it wants some callback 
methods run when new buddies join the Activity and when existing buddies leave the 
Activity. Everything you need to know about your buddies can be found in the code 
above, except how to send messages to them. For that we use the Text Channel. 
There is no need to learn about the Text Channel in great detail because the 
TextChannelWrapper class does everything you'll ever need to do with the TextChannel 
and hides the details from you. 

def entry_activate_cb (self , entry): 
text = entry .props . text 
logger . debug (' Entry : %s ' % text) 
if text: 

self . add_text (self . owner , text) 
entry . props . text = ' ' 
if self . text_channel : 

self. text_channel. send (text) 
else : 

logger . debug ( 

'Tried to send message but text ' 
'channel not connected.') 

The add_text() method is of interest. It takes the owner of the message and figures out 
what colors belong to that owner and displays the message in those colors. In the case 
of messages sent by the Activity it gets the owner like this in the init () method: 

self. owner = self .pservice . get_owner ( ) 
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In the case of received messages it gets the buddy the message came from: 

def _received_cb ( self , buddy, text) : 

"""Show message that was received.""" 
if buddy: 

nick = buddy .props . nick 
else : 

nick = ' ??? ' 
logger . debug (' Received message from %s: %s', 

nick, text) 
self . add_text (buddy, text) 

But what if we want to do more than just send text messages back and forth? What do 
we use for that? 

It's A Series Of Tubes! 

No, not the Internet. Telepathy has a concept called Tubes which describes the way 
instances of an Activity can communicate together. What Telepathy does is take the 
Text Channel and build Tubes on top of it. There are two kinds of Tubes: 

• D-Bus Tubes 

• Stream Tubes 

A D-Bus Tube is used to enable one instance of an Activity to call methods in the 
Buddy instances of the Activity. A Stream Tube is used for sending data over 
Sockets, for instance for copying a file from one instance of an Activity to another. A 
Socket is a way of communicating over a network using Internet Protocols. For instance 
the HTTP protocol used by the World Wide Web is implemented with Sockets. In the 
next example we'll use HTTP to transfer books from one instance of Read Etexts III to 
another. 

Read Etexts III, Now with Book Sharing! 

The Git repository with the code samples for this book has a file named 
ReadEtextsActivity3.py in the Making Shared_Activities directory which looks like 
this: 

import sys 
import os 
import logging 
import tempfile 
import time 
import zipfile 
import pygtk 
import gtk 
import pango 
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import dbus 

import gobject 

import telepathy 

from sugar . activity import activity 

from sugar . graphics import style 

from sugar import network 

from sugar . datastore import datastore 

from sugar . graphics . alert import NotifyAlert 

from toolbar import ReadToolbar, ViewToolbar 

from gettext import gettext as _ 

page=0 

PAGE_SIZE =45 
TOOLBAR_READ = 2 

logger = logging . getLogger (' read-etexts2-activity ' ) 

class ReadHTTPRequestHandler ( 

network. Chun kedGlibHTTPRequestHandler) : 

"""HTTP Request Handler for transferring document 

while collaborating. 

RequestHandler class that integrates with Glib 
mainloop. It writes the specified file to the 
client in chunks, returning control to the 
mainloop between chunks . 



def translate_path (self , path): 

"""Return the filepath to the shared document.""" 
return self . server . filepath 



class ReadHTTPServer (network. GlibTCPServer) : 

"""HTTP Server for transferring document while 

collaborating. ' 

def init (self, server_address , filepath) : 

"""Set up the GlibTCPServer with the 

ReadHTTPRequestHandler . 

filepath -- path to shared document to be served. 
ii ii ii 

self . filepath = filepath 

network. GlibTCPServer . init (self, 

server address , ReadHTTPRequestHandler) 



class ReadURLDownloader (network . GlibURLDownloader) : 

" " "URLDownloader that provides content-length and 
content-type . " " " 

def get_content_length (self ) : 

"""Return the content-length of the download.""" 
if self._info is not None: 

return int (self. _inf o . headers. get ( 
'Content-Length' ) ) 



def get_content_type (self ) : 
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"""Return the content-type of the download.""" 
if self._info is not None: 

return self . _inf o .headers. get ( 'Content-type' ) 
return None 

READ_STREAM_SERVICE = ' read-etexts-activity-http ' 

class ReadEtextsActivity (activity .Activity) : 

def init (self, handle) : 

"The entry point to the Activity" 

global page 

activity .Activity . init (self, handle) 

self . f ileserver = None 

self . ob j ect_id = handle . obj ect_id 

toolbox = activity . ActivityToolbox (self ) 
activity_toolbar = toolbox . get_activity_toolbar ( ) 
activity_toolbar . keep .props . visible = False 

self . edit_toolbar = activity . EditToolbar ( ) 
self . edit_toolbar . undo .props . visible = False 
self . edit_toolbar . redo .props . visible = False 
self . edit_toolbar . separator .props . visible = False 
self . edit_toolbar . copy . set_sensitive (False) 
self . edit_toolbar .copy. connect ( 'clicked' , 

self . edit_toolbar_copy_cb) 
self . edit_toolbar . paste .props . visible = False 
toolbox . add_toolbar (_ ( ' Edit ' ) , self. edit_toolbar ) 
self . edit_toolbar . show ( ) 

self . read_toolbar = ReadToolbar ( ) 

toolbox . add_toolbar (_ ( ' Read ' ) , self. read_toolbar ) 

self . read_toolbar .back. connect ( 'clicked' , 

self . go_back_cb) 
self . read_toolbar .forward. connect ( 'clicked' , 

self . go_f orward_cb) 
self . read_toolbar . num_page_entry .connect ( 'activate' , 

self . num_page_entry_activate_cb) 
self . read_toolbar . show ( ) 

self . view_toolbar = ViewToolbar ( ) 

toolbox . add_toolbar (_ ( ' View ' ) , self . view_toolbar ) 

self . view_toolbar .connect ( 'go-fullscreen' , 

self . view_toolbar_go_f ullscreen_cb) 
self . view_toolbar . zoom_in .connect ( 'clicked' , 

self . zoom_in_cb) 
self . view_toolbar . zoom_out .connect ( 'clicked' , 

self . zoom_out_cb) 
self . view_toolbar . show ( ) 

self . set_toolbox (toolbox) 

toolbox . show ( ) 

self . scrolled_window = gtk . ScrolledWindow ( ) 

self. scrolled_window. set_policy (gtk. POLICY_NEVER, 

gtk. POLICY_AUTOMATIC) 
self . scrolled_window .props . shadow_type = \ 

gtk.SHADOW_NONE 
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self . textview = gtk . TextView ( ) 
self .textview. set_edi table (False) 
self. textview. set_cursor_visible (False) 
self. textview. set_lef t_margin (50 ) 
self. textview. connect ( "key_press_event" , 
self . keypress_cb) 

self . progressbar = gtk . ProgressBar ( ) 
self.progressbar. set_orientation ( 

gtk. PROGRESS_LEFT_TO_RIGHT) 
self.progressbar.set_fraction(0.0) 

self . scrolled_window . add (self. textview) 

self. textview. show() 

self . scrolled_window . show ( ) 

vbox = gtk.VBox() 

vbox . pack_start (self.progressbar, False, 

False, 10) 
vbox . pack_start (self . scrolled_window) 
self . set_canvas (vbox) 
vbox . show ( ) 

page = 

self . clipboard = gtk . Clipboard ( 

display=gtk . gdk . display_get_def ault () , 

select ion=" CLIPBOARD") 
self. textview. grab_ focus ( ) 
self . f ont_desc = pango . FontDescription ( "sans %d" % 

style . zoom ( 10 ) ) 
self. textview . modif y_f ont (self . f ont_desc) 

buffer = self . textview . get_buffer ( ) 
self .markset_id = buff er . connect ( "mark-set" , 
self .mark_set_cb) 

self . toolbox . set_current_toolbar (TOOLBAR_READ) 

self . unused_download_tubes = set () 

self . want_document = True 

self . download_content_length = 

self . download_content_type = None 

# Status of temp file used for write_file: 

self . tempf ile = None 

self . close_requested = False 

self. connect ("shared", self. shared_cb) 

self . is_received_document = False 

if self ._shared_activity and \ 
handle . obj ect_id == None: 

# We're joining, and we don't already have 

# the document. 

if self . get_shared ( ) : 

# Already joined for some reason, just get the 

# document 

self . j oined_cb (self) 
else : 
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# Wait for a successful join before trying to get 

# the document 

self. connect ("joined", self.j oined_cb) 

def keypress_cb ( self , widget, event): 

"Respond when the user presses one of the arrow keys" 

keyname = gtk . gdk . keyval_name (event . keyval) 

print keyname 

if keyname == 'plus' : 

self . f ont_increase ( ) 

return True 
if keyname == 'minus' : 

self . f on t_de crease ( ) 

return True 
if keyname == ' Page_Up ' : 

self . page_previous () 

return True 
if keyname == ' Page_Down ' : 

self . page_next ( ) 

return True 
if keyname == 'Up' or keyname == ' KP_Up ' \ 
or keyname == 'KP_Left' : 

self . scroll_up ( ) 

return True 
if keyname == 'Down' or keyname == ' KP_Down ' \ 
or keyname == 'KP_Right' : 

self . scroll_down ( ) 

return True 
return False 

def num_page_entry_activate_cb (self , entry): 
global page 
if entry . props . text : 

new_page = int (entry .props . text ) - 1 
else : 

new_page = 

if new_page >= self . readtoolbar . total_pages : 

new_page = self . readtoolbar . total_pages - 1 

elif new_page < 0: 
new_page = 

self . read_toolbar . current_page = newpage 

self . read_toolbar . set_current_page (new_page) 

self . show_page (new_page) 

entry . props . text = str (newpage + 1) 

self . read_toolbar . update navbuttons ( ) 

page = new_page 

def go_back_cb ( self , button) : 
self . page_previous () 

def go_f orward_cb ( self , button): 
self . page_next ( ) 

def page_previous ( self ) : 
global page 
page=page-l 
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if page < 0: page=0 

self . readtoolbar . set_current_page (page) 

self . show_page (page) 

v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . upper - \ 

v_adj ustment .page_size 

def page_next ( self ) : 
global page 
page=page+l 

if page >= len (self .page_index) : page=0 
self . readtoolbar . set_current_page (page) 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . lower 

def zoom_in_cb (self , button) : 
self . f ont_increase ( ) 

def zoom_out_cb (self , button) : 
self . f on t_de crease ( ) 

def f ont_decrease (self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size - 1 
if font_size < 1: 
font_size = 1 
self . f ont_desc . set_size ( f ont_size * 1024) 
self .textview . modif y_f ont (self . f ont_desc) 

def f ont_increase (self ) : 

font^size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size + 1 

self . f ont_desc . set_size ( f ont_size * 1024) 
self. textview .modif y_f ont (self . f ont_desc) 

def mark_set_cb (self , textbuffer, iter, textmark) : 

if textbuf f er . get_has_selection ( ) : 

begin, end = textbuf fer . get_selection_bounds ( ) 
self . edit_toolbar . copy . set_sensitive (True) 

else : 

self . edit_toolbar . copy . set_sensitive (False) 

def edit_toolbar_copy_cb (self , button): 

textbuffer = self . textview . get_buf fer ( ) 
begin, end = textbuf fer . get_selection_bounds ( ) 
copy_text = textbuf fer . get_text (begin, end) 
self. clipboard. set_text (copy_text ) 

def view_toolbar_go_f ullscreen_cb (self , view_toolbar ) : 
self. fullscreen () 

def scroll_down (self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
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if v_adj ustment . value == v_adjustment . upper - \ 
v_adjustment .page_size: 
self . page_next ( ) 
return 
if v_adj ustment . value < v_adj ustment . upper - \ 
v_adj ustment .page_size: 
new_value = v_adjustment . value + \ 

v_adj ustment . step_increment 
if new_value > v_adjustment . upper - \ 
v_adj ustment .page_size: 
new value = v adjustment . upper - \ 
v_adj ustment .page_size 
v adj ustment . value = new value 

def scroll_up ( self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . lower : 
self . page_previous () 
return 
if v_adj ustment . value > v_adjustment . lower : 
new value = v adjustment . value - \ 

v_adj ustment . step_increment 
if new_value < v_adjustment . lower : 
new_value = v_adjustment . lower 
v adj ustment . value = new value 

def show_page ( self , pagenumber) : 

global PAGE_SIZE, current_word 

position = self . page_index [pagenumber ] 

self . etext_f ile . seek (position) 

linecount = 

label_text = '\n\n\n' 

textbuffer = self . textview . get_buf f er ( ) 

while linecount < PAGE_SIZE: 

line = self . etext_f ile . readline ( ) 
label_text = label_text + Unicode (line, 

'iso-8859-1') 
linecount = linecount + 1 

label_text = label_text + '\n\n\n' 

textbuffer. set_text (label_text ) 

self. textview. set_buf f er (textbuffer) 

def save_extracted_f ile (self , zipfile, filename) : 

"Extract the file to a temp directory for viewing' 
filebytes = zipfile . read ( filename) 
outfn = self .make_new_f ilename ( filename) 
if (outfn == ' ' ) : 

return False 
f = open (os .path. join (self . get_activity_root () , 

'tmp', outfn), 'w') 
try : 

f. write (filebytes) 
finally: 

f . close ( ) 

def get_saved_page_number (self ) : 
global page 
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title = self .metadata . get (' title ' , '') 
if title == ' ' or not \ 

title[len(title)-l] . isdigit ( ) : 
page = 
else : 

i = len(title) - 1 
newPage = ' ' 

while (title[i] .isdigit() and i > 0) : 
newPage = title [i] + newPage 
i = i - 1 
if title [i] == ' P' : 

page = int (newPage) - 1 
else : 

# not a page number; maybe a 

# volume number, 
page = 

def save_page_number (self ) : 
global page 

title = self .metadata . get (' title ' , '') 
if title == ' ' or not \ 

title [len (title) - 1 ]. isdigit () : 
title = title + ' P' + str(page + 1) 
else : 

i = len(title) - 1 

while (title[i] .isdigit() and i > 0) : 

i = i - 1 
if title [i] == ' P' : 

title = title[0:i] + 'P' + str (page + 1) 
else : 

title = title + ' P' + str(page + 1) 
self .metadata [' title ' ] = title 

def read_f ile ( self , filename) : 
"Read the Etext file" 
global PAGE_SIZE, page 

tempfile = os .path . j oin (self . get_activity_root () , 

'instance', 'tmp%i' % time . time () ) 
os . link ( filename, tempfile) 
self . tempfile = tempfile 

if zipf ile . is_zipf ile ( filename) : 

self.zf = zipf ile . ZipFile (filename, 'r') 
self . book_f iles = self . zf . namelist ( ) 
self . save_ext r act ed_ file (self . zf , 

self .book_filesT0] ) 
currentFileName = os .path . j oin ( 
self . get_activity_root () , 
' tmp ' , self .book_f iles [ ] ) 
else : 

currentFileName = filename 

self . etext_f ile = open (currentFileName, "r" ) 

self . page_index = [ ] 

pagecount = 

linecount = 

while self. etext file: 
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line = self . etext_f ile . readline ( ) 
if not line: 

break 
linecount = linecount + 1 
if linecount >= PAGE_SIZE: 

position = self . etext_f ile . tell ( ) 
self . page_index . append (position) 
linecount = 
pagecount = pagecount + 1 
if filename . endswith (". zip" ) : 

os . remove (currentFileName) 
self . get_saved_page_number ( ) 
self . show_page (page) 
self . read_toolbar . set_total_pages ( 

pagecount + 1) 
self . read_toolbar . set_current_page (page) 

# We've got the document, so if we're a shared 

# activity, offer it 
if self . get_shared ( ) : 

self . watch_f or_tubes () 
self . share_document ( ) 

def make_new_f ilename ( self , filename) : 

partition_tuple = f ilename . rpartition ('/' ) 
return partition tuple [2] 

def write_f ile (self , filename) : 

"Save meta data for the file." 
if self . is_received_document : 

# This document was given to us by someone, so 

# we have to save it to the Journal . 
self . etext_f ile . seek ( ) 

filebytes = self . etext_f ile . read ( ) 

f = open ( filename, ' wb ' ) 

try: 

f. write (filebytes) 
finally: 

f . close ( ) 
elif self . tempf ile : 

if self . closerequested: 

os . link ( self . tempf ile, filename) 
logger . debug ( 

"Removing temp file %s because we " 
"will close", 
self . tempf ile) 
os.unlink(self. tempf ile) 
self . tempf ile = None 
else : 

# skip saving empty file 
raise NotlmplementedError 

self .metadata [' activity ' ] = self . get_bundle_id ( ) 
self . save_page_number ( ) 

def can_close ( self ) : 

self . close_requested = True 
return True 
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def j oined_cb ( self , also_self ) : 

"""Callback for when a shared activity is joined. 

Get the shared document from another participant. 
ii ii ii 

self . watch_f ortubes () 

gob j ect . idle_add (self . get_document ) 

def get_document (self ) : 

if not self . want_document : 
return False 

# Assign a file path to download if one 

# doesn't exist yet 

if not self . _j obj ect . file_path : 

path = os .path . j oin (self . get_activity_root () , 
' instance ' , 

'tmp%i' % time. time ()) 
else : 

path = self . _j obj ect . file_path 

# Pick an arbitrary tube we can try to 

# download the document from 
try : 

tube_id = self . unused_download_tubes . pop ( ) 
except (ValueError, KeyError) , e: 
logger . debug ( 

'No tubes to get the document ' 

'from right now: %s', 

e) 
return False 

# Avoid trying to download the document multiple 

# timesat once 

self . want_document = False 

gob j ect . idle_add (self . download_document , tube_id, path) 

return False 

def download_document (self , tube_id, path): 

chan = self ._shared_activity . telepathy_tubes_chan 
iface = chanTtelepathy.CHANNEL_TYPE_TUBES] 
addr = if ace . AcceptStreamTube (tube_id, 

telepathy. S0CKET_ADDRESS_TYPE_IPV4 , 

telepathy . SOCKET_ACCESS_CONTROL_LOCALHOST, 0, 

utf8_strings=True) 
logger . debug (' Accepted stream tube: ' 

'listening address is %r', 

addr) 
assert isinstance (addr, dbus. Struct) 
assert len (addr) == 2 
assert isinstance (addr [ ] , str) 
assert isinstance (addr [ 1 ] , (int, long)) 
assert addr[l] > and addr[l] < 65536 
port = int(addr[l]) 

self.progressbar.show() 
getter = ReadURLDownloader ( 
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"http : //%s : %d/ document" 

% (addr [0] , port) ) 
getter. connect ("finished", 

self . download_result_cb, tube_id) 
getter. connect ("progress", 

self . download_progress_cb, tube_id) 
getter. connect ("error", 

self . download_error_cb, tube_id) 
logger . debug ( "Starting download to %s...", path) 
getter. start (path) 
self . download_content_length = \ 

getter . get_content_length ( ) 
self . download_content_type = \ 

getter . get_content_type ( ) 
return False 

def download_progress_cb (self , getter, 
bytes_downloaded, tube_id) : 
if self . download_content_length > 0: 
logger . debug ( 

"Downloaded %u of %u bytes from tube %u. . ." 
bytes_downloaded, 
self . download_content_length, 
tube_id) 
else : 

logger . debug ( "Downloaded %u bytes from tube %u. 
bytes_downloaded, tube_id) 
total = self . download_content_length 
self . set_downloaded_bytes (bytes_down loaded, total ) 
gtk . gdk . threads_enter ( ) 
while gtk . events_pending ( ) : 

gtk . main_iteration ( ) 
gtk . gdk . threads_leave ( ) 

def set_downloaded_bytes (self , bytes, total): 
fraction = float (bytes) / float (total) 
self.progressbar. set_fraction (fraction) 
logger . debug ( "Downloaded percent", fraction) 

def clear_downloaded_bytes (self ) : 

self.progressbar. set_fraction (0 . 0) 
logger . debug ( "Cleared download bytes") 

def download_error_cb ( self , getter, err, tube_id) : 
self . progressbar . hide () 
logger . debug ( 

"Error getting document from tube %u: %s", 

tube_id, err) 
self. alert (_(' Failure') , 

_( 'Error getting document from tube')) 
self . want_document = True 
self . download_content_length = 
self . download_content_type = None 
gobj ect . idle_add ( self . get_document ) 

def download_result_cb (self , getter, tempfile, 
suggested_name, tube_id) : 
if self . download_content_type .startswith( 
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'text/html' ) : 

# got an error page instead 

self . download_error_cb (getter, 

'HTTP Error', tube_id) 
return 

del self . unused_download_tubes 

self . tempf ile = tempfile 

file_path = os .path . j oin (self . get_activity_root () , 

'instance', '%i' % time . time () ) 
logger . debug ( 

"Saving file %s to datastore . . . " , file_path) 
os . link (tempf ile, file_path) 
self . _j ob j ect . f ile_path = file_path 
datastore . write (self . _j obj ect , 

transf er_ownership=True) 

logger . debug ( 

"Got document %s (%s) from tube %u", 
tempfile, suggested_name, tube_id) 

self . is_received_document = True 

self . read_f ile (tempfile) 

self . save ( ) 

self . progressbar . hide () 

def shared_cb ( self , activityid) : 

"""Callback when activity shared. 

Set up to share the document . 



# We initiated this activity and have now shared it, 

# so by definition we have the file, 
logger . debug (' Activity became shared') 
self . watch_f ortubes () 

self . share_document ( ) 

def share_document (self ) : 

"""Share the document.""" 
h = hash ( self ._activity_id) 
port = 1024 + Th % 64511) 
logger . debug ( 

'Starting HTTP server on port %d', port) 
self . f ileserver = ReadHTTPServer ( ( " " , port), 
self . tempfile) 

# Make a tube for it 

chan = self ._shared_activity . telepathy_tubes_chan 
iface = chan [telepathy. CHANNEL_TYPE_TUBES] 
self . f ileserver_tube_id = if ace . Of f erStreamTube ( 
READ_STREAM_SERVICE, 

U, 

telepathy. SOCKET_ADDRESS_TYPE_IPV4 , 
('127.0.0.1', dbus . UIntl6 (port) ) , 
telepathy. SOCKET_ACCESS_CONTROL_LOCALHOST, 
0) 
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def watch_f or_tubes ( self ) : 

"""Watch for new tubes.""" 

tubes_chan = self ._shared_activity . telepathy_tubes_chan 

tubes_chan [telepathy . CHANNEL_TYPE_TUBES] . \ 

connect_to_signal ( 

' NewTube ' , self . new_tube_cb) 
tubes_chan [telepathy . CHANNEL_TYPE_TUBES] .ListTubes ( 

reply_handler=self . list_tubes_reply_cb, 

error_handler=self . list_tubes_error_cb) 

def new_tube_cb ( self , tube_id, initiator, tube_type, 

service, params, state) : 

"""Callback when a new tube becomes available.""" 

logger . debug ( 

'New tube: ID=%d initator=%d type=%d service=%s ' 
'params=%r state=%d', tube_id, initiator, 
tube_type, service, params, state) 

if service == READ_STREAM_SERVICE : 

logger . debug (' I could download from that tube') 
self . unused_download_tubes . add (tube_id) 

# if no download is in progress, let's fetch 

# the document 

if self . want_document : 

gob j ect . idle_add (self . get_document ) 

def list_tubes_reply_cb (self , tubes): 

"""Callback when new tubes are available.""" 
for tube_info in tubes: 

self . new_tube_cb ( *tube_inf o) 

def list_tubes_error_cb (self , e): 

"""Handle ListTubes error by logging.""" 
logger . error (' ListTubes ( ) failed: %s ' , e) 

def alert (self, title, text=None) : 
alert = Notif yAlert (timeout=20 ) 
alert . props . title = title 
alert . props .msg = text 
self . add_alert (alert) 

alert. connect ('response', self. alert_cancel_cb) 
alert . show ( ) 

def alert_cancel_cb ( self , alert, response_id) : 
self . remove_alert (alert) 
self.textview. grab_f ocus ( ) 

The contents of activity.info are these lines: 

[Activity] 

name = Read Etexts III 

service_name = net . f lossmanuals . ReadEtextsActivity 

icon = read-etexts 

exec = sugar-activity ReadEtextsActivity3 . ReadEtextsActivity 

show_launcher = no 

activity version = 1 

mime_types = text/plain; application/zip 

license = GPLv2+ 
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To try it out, download a Project Gutenberg book to the Journal, open it with this latest 
Read Etexts III, then share it with a second user who has the program installed but not 
running. She should accept the invitation to join that appears in her Neighborhood 
view. When she does Read Etexts II will start up and copy the book from the first user 
over the network and load it. The Activity will first show a blank screen, but then a 
progress bar will appear just under the toolbar and indicate the progress of the copying. 
When it is finished the first page of the book will appear. 

So how does it work? Let's look at the code. The first points of interest are the class 
definitions that appear at the beginning: ReadHTTPRequestHandler, 
ReadHTTPServer, and ReadURLDownloader. These three classes extend (that is to 
say, inherit code from) classes provided by the sugar.network package. These classes 
provide an HTTP client for receiving the book and an HTTP Server for sending the 
book. 

This is the code used to send a book: 

def shared_cb ( self , activityid) : 

"""Callback when activity shared. 

Set up to share the document . 



# We initiated this activity and have now shared it, 

# so by definition we have the file. 
logger . debug (' Activity became shared') 
self . watch_f ortubes () 

self . share_document ( ) 

def share_document (self ) : 

"""Share the document.""" 
h = hash ( self ._activity_id) 
port = 1024 + Th % 64511) 
logger . debug ( 

'Starting HTTP server on port %d', port) 
self . f ileserver = ReadHTTPServer (("" , port), 
self . tempf ile) 

# Make a tube for it 

chan = self ._shared_activity . telepathy_tubes_chan 
iface = chan [telepathy. CHANNEL_TYPE_TUBES] 
self . f ileserver_tube_id = if ace . Of f erStreamTube ( 
READ_STREAM_SERVICE, 

U, 

telepathy. SOCKET_ADDRESS_TYPE_IPV4, 
('127.0.0.1', dbus.UIntl6 (port) ) , 
telepathy. SOCKET_ACCESS_CONTROL_LOCALHOST, 
0) 
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You will notice that a hash of the _activity _id is used to get a port number. That port is 
used for the HTTP server and is passed to Telepathy, which offers it as a Stream 
Tube. On the receiving side we have this code: 

def j oined_cb ( self , also_self ) : 

"""Callback for when a shared activity is joined. 

Get the shared document from another participant. 
ii ii ii 

self . watch_f or_tubes () 

gobj ect . idle_add ( self . get_document ) 

def get_document ( self ) : 

if not self . want_document : 
return False 

# Assign a file path to download if one doesn't 

# exist yet 

if not self . _j obj ect . file_path : 

path = os .path. join (self . get_activity_root () , 
' instance ' , 

' tmp%i' % time. time () ) 
else : 

path = self . _j obj ect . file_path 

# Pick an arbitrary tube we can try to download the 

# document from 
try : 

tube_id = self . unused_download_tubes . pop ( ) 
except (ValueError, KeyError) , e: 
logger . debug ( 

'No tubes to get the document from ' 

' right now : %s ' , 

e) 
return False 

# Avoid trying to download the document multiple 

# times at once 

self . want_document = False 

gobj ect . idle_add ( self . download_document , 

tube_id, path) 
return False 

def download_document ( self , tube_id, path): 

chan = self ._shared_activity . telepathy_tubes_chan 
iface = chan [telepathy. CHANNEL_TYPE_TUBES] 
addr = if ace . AcceptStreamTube (tube_id, 

telepathy. S0CKET_ADDRESS_TYPE_IPV4 , 

telepathy. SOCKET_ACCESS_CONTROL_LOCALHOST, 

0, 

utf8_strings=True) 
logger . debug ( 

'Accepted stream tube: listening address is %r', 

addr) 
assert isinstance (addr, dbus. Struct) 
assert len (addr) == 2 
assert isinstance (addr [ ] , str) 
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assert isinstance (addr [ 1 ] , (int, long)) 
assert addrfl] > and addr[l] < 65536 
port = int(addr[l]) 

self .progressbar.showf) 
getter = ReadURLDownloader ( 

"http: //%s:%d/document" 

% (addr [0] , port) ) 
getter. connect ("finished", 

self . download_result_cb, tube_id) 
getter. connect ("progress", 

self . download_progress_cb, tube_id) 
getter. connect ("error", 

self . download_error_cb, tube_id) 
logger . debug ( 

"Starting download to %s...", path) 
getter. start (path) 
self . download_content_length = \ 

getter . get_content_length ( ) 
self . download_content_type = \ 

getter . get_content_type ( ) 
return False 

def download_progress_cb (self , getter, 
bytes_downloaded, tube_id) : 
if self . download_content_length > 0: 
logger . debug ( 

"Downloaded %u of %u bytes from tube %u. 
bytes_downloaded, 
self . download_content_length, 
tube_id) 
else : 

logger . debug ( 

"Downloaded %u bytes from tube %u...", 
bytes_downloaded, tube_id) 
total = self . download_content_length 
self . set_downloaded_bytes (bytes_downloaded, 

total) 
gtk . gdk . threads_enter ( ) 
while gtk . events_pending ( ) : 

gtk .main_iteration ( ) 
gtk . gdk . threads_leave () 

def download_error_cb (self , getter, err, tube_id) : 
self . progressbar . hide () 
logger . debug ( 

"Error getting document from tube %u: %s", 

tube_id, err) 
self. alert (_(' Failure') , 

_(' Error getting document from tube')) 
self . want_document = True 
self . download_content_length = 
self . download_content_type = None 
gob j ect . idle_add (self . get_document ) 

def download_result_cb (self , getter, tempfile, 
suggested name, tube_id) : 
if self . download_content_type . startswith ( 
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'text/html ' ) : 

# got an error page instead 

self . download_error_cb (getter, 

'HTTP Error', tube_id) 
return 

del self . unused_download_tubes 

self . tempf ile = tempfile 

file_path = os . path . j oin (self . get_activity_root () , 

' instance ' , 

'%i ' % time. time () ) 
logger . debug ( 

"Saving file %s to datastore . . . " , file_path) 
os . link (tempf ile, file_path) 
self . _j ob j ect . f ile_path = file_path 
datastore. write (self._jobject, 

transf er_ownership=True) 

logger . debug ( 

"Got document %s (%s) from tube %u", 

tempfile, suggested_name, tube_id) 
self . is_received_document = True 
self . read_f ile (tempfile) 
self . save ( ) 
self . progressbar . hide () 

Telepathy gives us the address and port number associated with a Stream Tube and we 
set up the HTTP Qient to read from it. The client reads the file in chunks and calls 
download_progress_cb() after every chunk so we can update a progress bar to show the 
user how the download is progressing. There are also callback methods for when there 
is a download error and for when the download is finished, 

The ReadURLDownloader class is not only useful for transferring files over Stream 
Tubes, it can also be used to interact with websites and web services. My Activity Get 
Internet Archive Books uses this class for that purpose. 

The one remaining piece is the code which handles getting Stream Tubes to download 
the book from. In this code, adapted from the Read Activity, as soon as an instance of 
an Activity receives a book it turns around and offers to share it, thus the Activity may 
have several possible Tubes it could get the book from: 

READ_STREAM_SERVICE = ' read-etexts-activity-http ' 



def watch_f or_tubes ( self ) : 

"""Watch for new tubes. 

tubes_chan = self ._shared_activity . \ 
telepathy_tubes_chan 

tubes_chan [telepathy . CHANNEL_TYPE_TUBES] . \ 
connect_to_signal ( 
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'NewTube ' , 
self . new_tube_cb) 
tubes_chan [telepathy . CHANNEL_TYPE_TUBES] . \ 
ListTubes ( 

reply_handler=self . list_tubes_reply_cb, 
error_handler=self . list_tubes_error_cb) 

def new_tube_cb (self , tube_id, initiator, 
tube_type, service, params, state) : 
"""Callback when a new tube becomes available.""" 
logger . debug ( 

'New tube: ID=%d initator=%d type=%d service=%s ' 

'params=%r state=%d', tube_id, initiator, 

tube_type, 

service, params, state) 
if service == READ_STREAM_SERVICE : 

logger . debug (' I could download from that tube') 

self . unused_download_tubes . add (tube_id) 

# if no download is in progress, 

# let's fetch the document 
if self . want_document : 

gob j ect . idle_add (self . get_document ) 

def list_tubes_reply_cb (self , tubes): 

"""Callback when new tubes are available.""" 
for tube_info in tubes: 

self . new_tube_cb ( *tube_inf o) 

def list_tubes_error_cb (self , e): 

"""Handle ListTubes error by logging.""" 
logger . error (' ListTubes ( ) failed: %s', e) 

The READ STREAM SERVICE constant is defined near the top of the source file. 

Using D-Bus Tubes 

D-Bus is a method of supporting IPC, or Inter-Process Communication, that was 
created for the GNOME desktop environment. The idea of IPC is to allow two running 
programs to communicate with each other and execute each other's code. GNOME uses 
D-Bus to provide communication between the desktop environment and the programs 
running in it, and also between GNOME and the operating system. A D-Bus Tube is 
how Telepathy makes it possible for an instance of an Activity running on one 
computer to execute methods in another instance of the same Activity running on a 
different computer. Instead of just sending simple text messages back and forth or 
doing file transfers, your Activities can be truly shared. That is, your Activity can allow 
many people to work on the same task together. 



136 



I have never written an Activity that uses D-Bus Tubes myself, but many others have. 
We're going to take a look at code from two of them: Scribble by Sayamindu Dasgupta 
and Batalla Naval, by Gerard J. Cerchio and Andres Ambrois, which was written for 
the Ceibal Jam. 

Scribble is a drawing program that allows many people to work on the same drawing 
at the same time. Instead of allowing you to choose what colors you will draw with, it 
uses the background and foreground colors of your Buddy icon (the XO stick figure) to 
draw with. That way, with many people drawing shapes it's easy to know who drew 
what. If you join the Activity in progress Scribble will update your screen so your 
drawing matches everyone else's screen. Scribble in action looks like this: 




Batalla Naval is a version of the classic game Battleship. Each player has two grids: one 
for placing his own ships (actually the computer places the ships for you) and another 
blank grid representing the area where your opponent's ships are. You can't see his 
ships and he can't see yours. You click on the opponent's grid (on the right) to indicate 
where you want to aim an artillery shell. When you do the corresponding square will 
light up in both your grid and your opponent's own ship grid. If the square you picked 
corresponds to a square where your opponent has placed a ship that square will show 
up in a different color. The object is to find the squares containing your opponent's 
ships before he finds yours. The game in action looks like this: 
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I suggest that you download the latest code for these two Activities from Gitorious using 
these commands: 

mkdir scribble 

cd scribble 

git clone git : //git . sugarlabs . org/scribble/mainline . git 

cd . . 

mkdir batallanaval 

cd batallanaval 

git clone git : //git . sugarlabs . org/batalla-naval/mainline . git 

You'll need to do some setup work to get these running in sugar-emulator. Scribble 
requires the goocanvas GTK component and the Python bindings that go with it. 
These were not installed by default in Fedora 10 but I was able to install them using 
Add/Remove Programs from the System menu in GNOME. Batalla Naval is missing 
setup.py, but that's easily fixed since every setup.py is identical. Copy the one from 
the book examples into the mainline/BatallaNaval.activity directory and run 
./setup.py dev on both Activities. 

These Activities use different strategies for collaboration. Scribble creates lines of 
Python code which it passes to all Buddies and the Buddies use exec to run the 
commands. This is the code used for drawing a circle: 



def process_item_f inalize (self , x, y) : 
if self. tool == 'circle': 

self.cmd = "goocanvas . Ellipse ( 
parent=self._root, 
center x=%d, 
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center_y=%d, radiusx = %d, 

radius_y = %d, 

f ill_color_rgba = %d, 

strokecolorrgba = %d, 

title = '%s')" % (self . item. props . center_x, 

self . item. props . center_y, 

self . item. props . radiusx, 

self.item.props.radius_y, 

self . _f ill_color , 

self, stroke color, self. item id) 



def processcmd ( self , cmd) : 

#print 'Processing cmd : ' + cmd 

exec (cmd) 

#FIXME: Ugly hack, but I'm too lazy to 

# do this nicely 

if len (self . cmd_list) > 0: 

self . cmd_list += (';' + cmd) 
else : 

self . cmd_list = cmd 

The cmd_list variable is used to create a long string containing all of the commands 
executed so far. When a new Buddy joins the Activity she is sent this variable to 
execute so that her drawing area has the same contents as the other Buddies have. 

This is an interesting approach but you could do the same thing with the TextChannel 
so it isn't the best use of D-Bus Tubes. Batalla Naval's use of D-Bus is more typical. 

How D-Bus Tubes Work, More Or Less 

D-Bus enables you to have two running programs send messages to each other. The 
programs have to be running on the same computer. Sending a message is sort of a 
roundabout way of having one program run code in another. A program defines the 
kind of messages it is willing to receive and act on. In the case of B atalla Naval it 
defines a message "tell me what square you want to fire a shell at and I'll figure out if 
part of one of my ships is in that square and tell you." The first program doesn't 
actually run code in the second one, but the end result is similar. D-Bus Tubes is a way 
of making D-Bus able to send messages like this to a program running on another 
computer. 
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Think for a minute about how you might make a program on one computer run code in 
a running program on a different computer. You'd have to use the network, of course. 
Everyone is familiar with sending data over a network, but in this case you would have 
to send program code over the network. You would need to be able to tell the running 
program on the second computer what code you wanted it to run. You would have to 
send it a method call and all the parameters you needed to pass into the method, and 
you'd need a way to get a return value back. 

Isn't that kind of like what Scribble is doing in the code we just looked at? Maybe we 
could make our code do something like that? 

Of course if you did that then every program you wanted to run code in remotely 
would have to be written to deal with that. If you had a bunch of programs you wanted 
to do that with you'd have to have some way of letting the programs know which 
requests were meant for it. It would be nice if there was a program running on each 
machine that dealt with making the network connections, converting method calls to 
data that could be sent over the network and then converting the data back into method 
calls and running them, plus sending any return values back. This program should be 
able to know which program you wanted to run code in and see that the method call is 
run there. The program should run all the time, and it would be really good if it made 
running a method on a remote program as simple as running a method in my own 
program. 

As you might guess, what I've just described is more or less what D-Bus Tubes are. 
There are articles explaining how it works in detail but it is not necessary to know how 
it works to use it. You do need to know about a few things, though. First, you need to 
know how to use D-Bus Tubes to make objects in your Activity available for use by 
other instances of that Activity running elsewhere. 

An Activity that needs to use D-Bus Tubes needs to define what sorts of messages it is 
willing to act on, in effect what specific methods in in the program are available for this 
use. All Activities that use D-Bus Tubes have constants like this: 

SERVICE = "org . randomink . sayamindu . Scribble" 

IFACE = SERVICE 

PATH = " /org/randomink/sayamindu/Scribble" 
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These are the constants used for the Scribble Activity. The first constant, named 
SERVICE, represents the bus name of the Activity. This is also called a well-known 
name because it uses a reversed domain name as part of the name. In this case 
Sayamindu Dasgupta has a website at http: //say amindu.randomink. org so he reverses 
the dot-separated words of that URL to create the first part of his bus name. It is not 
necessary to own a domain name before you can create a bus name. You can use 
org.sugarlabs.ActivityName if you like. The point is that the bus name must be 
unique, and by convention this is made easier by starting with a reversed domain 
name. 

The PATH constant represents the object path. It looks like the bus name with slashes 
separating the words rather than periods. For most Activities that is exactly what it 
should be, but it is possible for an application to expose more than one object to D-Bus 
and in that case each object exposed would have its own unique name, by convention 
words separated by slashes. 

The third constant is IFACE, which is the interface name. An interface is a collection 
of related methods and signals, identified by a name that uses the same convention 
used by the bus name. In the example above, and probably in most Activities using a 
D-Bus Tube, the interface name and the bus name are identical. 

So what is a signal? A signal is like a method but instead of one running program 
calling a method in one other running program, a signal is broadcast. In other words, 
instead of executing a method in just one program it executes the same method in many 
running programs, in fact in every running program that has that method that it is 
connected to through the D-Bus. A signal can pass data into a method call but it can't 
receive anything back as a return value. It's like a radio station that broadcasts music to 
anyone that is tuned in. The flow of information is one way only. 

Of course a radio station often receives phone calls from its listeners. A disc jockey 
might play a new song and invite listeners to call the station and say what they thought 
about it. The phone call is two way communication between the disc jockey and the 
listener, but it was initiated by a request that was broadcast to all listeners. In the same 
way your Activity might use a signal to invite all listeners (Buddies) to use a method to 
call it back, and that method can both supply and receive information. 
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In D-Bus methods and signals have signatures. A signature is a description of the 
parameters passed into a method or signal including its data types. Python is not a 
strongly typed language. In a strongly typed language every variable has a data type 
that limits what it can do. Data types include such things as strings, integers, long 
integers, floating point numbers, booleans, etc. Each one can be used for a specific 
purpose only. For instance a boolean can only hold the values True and False, nothing 
else. A string can be used to hold strings of characters, but even if those characters 
represent a number you cannot use a string for calculations. Instead you need to 
convert the string into one of the numeric data types. An integer can hold integers up to 
a certain size, and a long integer can hold much larger integers, A floating point 
number is a number with a decimal point in scientific notation. It is almost useless for 
business arithmetic, which requires rounded results. 

In Python you can put anything into any variable and the language itself will figure out 
how to deal with it. To make Python work with D-Bus, which requires strongly typed 
variables that Python doesn't have, you need a way to tell D-Bus what types the 
variables you pass into a method should have. You do this by using a signature string 
as an argument to the method or signal. Methods have two strings: an in signature 
and an out_signature. Signals just have a signature parameter. Some examples of 
signature strings: 



Two parameters, both integers 



Three parameters, all strings 



ixd 



Three parameters, an integer, a long integer, and a double precision floating point number. 



a(ssiii) 



An array where each element of the array is a tuple containing two strings and three integers. 



There is more information on signature strings in the dbus-python tutorial at 
http://dbus.freedesktop.org/doc/dbus-python/doc/tutorial.html . 

Introducing Hello Mesh And Friends 

If you study the source code of a few shared Activities you'll conclude that many of 
them contain nearly identical methods, as if they were all copied from the same source. 
In fact, more likely than not they were. The Activity Hello Mesh was created to be an 
example of how to use D-Bus Tubes in a shared Activity. It is traditional in 
programming textbooks to have the first example program be something that just prints 
the words "Hello World" to the console or displays the same words in a window. In that 
tradition Hello Mesh is a program that doesn't do all that much. You can find the code 
in Gitorious at http://git.sugarlabs.org/projects/hello-mesh . 
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Hello Mesh is widely copied because it demonstrates how to do things that all shared 
Activities need to do. When you have a shared Activity you need to be able to do two 
things: 

• Send information or commands to other instances of your Activity. 

• Give Buddies joining your Activity a copy of the current state of the Activity. 

It does this using two signals and one method: 

• A signal called HelloO that someone joining the Activity sends to all participants. 
The HelloO method takes no parameters. 

• A method called WorldO which instances of the Activity receiving HelloO send back 
to the sender. This method takes a text string as an argument, which is meant to 
represent the current state of the Activity. 

• Another signal called SendTextO which sends a text string to all participants. This 
represents updating the state of the shared Activity. In the case of Scribble this 
would be informing the others that this instance has just drawn a new shape. 

Rather than study Hello Mesh itself I'd like to look at the code derived from it used in 
Batalla Naval. I have taken the liberty of running the comments, originally in Spanish, 
through Google Tra nsla te to make everything in English. I have also removed some 
commented-out lines of code. 

This Activity does something clever to make it possible to run it either as a Sugar 
Activity or as a standalone Python program. The standalone program does not support 
sharing at all, and it runs in a Window. The class Activity is a subclass of Window, so 
when the code is run standalone the initO function in BatallaNaval.py gets a Window, 
and when the same code is run as an Activity the instance of class 
BatallaNavalActivity is passed to init(): 

from sugar . activity. activity import Activity, ActivityToolbox 

import BatallaNaval 

from Collaboration import CollaborationWrapper 



class BatallaNavalActivity (Activity) : 

' ' ' The Sugar class called when you run this 
program as an Activity. The name of this 
class file is marked in the 
activity/activity . info file. ' ' ' 

def init (self, handle) : 

Activity. init (self, handle) 

self . gamename = 'BatallaNaval' 

# Create the basic Sugar toolbar 
toolbox = ActivityToolbox (self ) 
self. set toolbox (toolbox) 
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toolbox . show ( ) 

# Create an instance of the CollaborationWrapper 

# so you can share the activity. 

self . colaboracion = CollaborationWrapper (self ) 

# The activity is a subclass of Window, so it 

# passses itself to the init function 
BatallaNaval . init (False, self) 

The other clever thing going on here is that all the collaboration code is placed in its own 
CollaborationWrapper class which takes the instance of the BatallNavalActivity class 
in its constructor. This separates the collaboration code from the rest of the program. 
Here is the code in CollaborationWrapper.py: 

import logging 

from sugar . presence import presenceservice 
import telepathy 

from dbus. service import method, signal 
# In build 656 Sugar lacks sugartubeconn 
try : 

from sugar . presence . sugartubeconn import \ 
SugarTubeConnection 
except : 

from sugar . presence . tubeconn import TubeConnection as \ 
SugarTubeConnection 
from dbus . gob j ect_service import ExportedGOb j ect 

' ' ' In all collaborative Activities in Sugar we are 

made aware when a player enters or leaves . So that 

everyone knows the state of the Activity we use 

the methods Hello and World. When a participant 

enters Hello sends a signal that reaches 

all participants and the participants 

respond directly using the method "World", 

which retrieves the current state of the Activity. 

After the updates are given then the signal 

Play is used by each participant to make his move. 

In short this module encapsulates the logic of 

"collaboration" with the following effect: 

- When someone enters the collaboration 
the Hello signal is sent. 

- Whoever receives the Hello signal responds 
with World 

- Every time someone makes a move he uses 
the method Play giving a signal which 
communicates to each participant 

what his move was. 



SERVICE = "org. ceibaljam. BatallaNaval" 

IFACE = SERVICE 

PATH = "/org/ceibaljam/BatallaNaval" 

logger = logging . getLogger (' BatallaNaval ' 
logger. setLevel (logging. DEBUG) 
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class CollaborationWrapper (ExportedGOb j ect ) : 

' ' ' A wrapper for the collaboration methods . 

Get the activity and the necessary callbacks, 



def init (self, activity) : 

self . activity = activity 
self . presence_service = \ 

presenceservice . get_instance () 
self. owner = \ 

self . presence_service . get_owner ( ) 

def set_up(self, buddy_j oined_cb, buddy_lef t_cb, 
World_cb, Play_cb, my_boats) : 
self. activity. connect ( ' shared' , 

self . _shared_cb) 
if self . activity ._shared_activity : 
# We are joining the activity 
self. activity. connect ( ' joined' , 

self . _j oined_cb) 
if self . activity . get_shared () : 
# We've already joined 
self . _j oined_cb ( ) 

self . buddy_j oined = buddy_j oined_cb 
self . buddy_lef t = buddy_lef t_cb 
self . World_cb = World_cb 

# Called when someone passes the board state. 
self.Play_cb = Play_cb 

# Called when someone makes a move. 

# Submitted by making World on a new partner 
self .my_boats = [(b.nombre, b . orientacion, 

b . largo, b . pos [ ] , 

b.posfl]) for b in my_boats] 
self. world = False 
self. entered = False 

def _shared_cb ( self , activity): 
self . _sharing_setup ( ) 
self . tubes_chan [telepathy . CHANNEL_TYPE_TUBES] . \ 

Of f erDBusTube ( 

SERVICE, {}) 
self . is_initiator = True 

def _j oined_cb ( self , activity): 

self . _sharing_setup ( ) 

self . tubes_chan [telepathy . CHANNEL_TYPE_TUBES] . \ 
ListTubes ( 

reply_handler=self . _list_tubes_reply_cb, 
error_handler=self . _list_tubes_error_cb) 

self . is_initiator = False 

def _sharing_setup ( self ) : 

if self . activity ._shared_activity is None: 
logger . error ( 

'Failed to share or join activity') 
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return 

self . conn = \ 

self. activity ._shared_activity . telepathy_conn 
self . tubes_chan = \ 

self. activity ._shared_activity . telepathy_tubes_chan 
self . text_chan = \ 

self. activity ._shared_activity . telepathy_text_chan 

self .tube schan [telepathy . CHANNEL_TYPE_TUBES ] . \ 
connect_to_signal ( 
'NewTube', self ._new_tube_cb) 

self. activity ._shared_activity .connect ( 

'buddy- j oined ' , 

self ._buddy_j oined_cb) 
self. activity ._shared_activity .connect ( 

'buddy-left ' , 

self . _buddy_lef t_cb) 

# Optional - included for example : 

# Find out who's already in the shared activity: 
for buddy in \ 

self. activity ._shared_activity . \ 

get_j oined_buddies () : 
logger . debug ( 

'Buddy %s is already in the activity', 

buddy .props .nick) 

def participant_change_cb (self , added, removed) : 
logger . debug ( 

'Tube: Added participants: %r', added) 
logger . debug ( 

'Tube: Removed participants: %r', removed) 
for handle, busnarae in added: 

buddy = self ._get_buddy (handle) 
if buddy is not None: 
logger . debug ( 

'Tube: Handle %u (Buddy %s) was added', 
handle, buddy .props . nick) 
for handle in removed: 

buddy = self ._get_buddy (handle) 
if buddy is not None: 

logger . debug (' Buddy %s was removed' % 
buddy .props .nick) 
if not self . entered: 

if self . is_initiator : 
logger . debug ( 

"I'm initiating the tube, " 
"will watch for hellos.") 
self . add_hello_handler ( ) 
else : 

logger . debug ( 

'Hello, everyone! What did I miss?') 
self .Hello () 
self. entered = True 
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# This is sent to all participants whenever we 

# join an activity 

@signal (dbus_interf ace=IFACE, signature^' ' ) 
def Hello (self) : 

"""Say Hello to whoever else is in the tube.""" 

logger . debug (' I said Hello.') 

# This is called by whoever receives our Hello signal 

# This method receives the current game state and 

# puts us in sync with the rest of the participants . 

# The current game state is represented by the 

# game object 

@method (dbus_interf ace=IFACE, in_signature= ' a (ssiii) ', 

out_signature= ' a ( ssiii) ') 
def World(self, boats): 

"""To be called on the incoming XO after 

they Hello. """ 

if not self. world: 

logger . debug (' Somebody called World on me') 
self. world = True # Instead of loading 

# the world, I am 

# receiving play by 

# play, 
self . World_cb (boats ) 

# now I can World others 
self . add_hello_handler ( ) 

else : 

self. world = True 

logger . debug ( 

"I've already been welcomed, doing nothing") 
return self .my_boats 

@ signal (dbus_interf ace=IFACE, signature='ii' ) 

def Play(self, x, y) : 

"""Say Hello to whoever else is in the tube.""" 
logger . debug (' Running remote play:%s x %s.', x, y) 

def add_hello_handler ( self ) : 

logger . debug (' Adding hello handler.') 

self. tube. add_signal_receiver (self . hello_signal_cb, 

'Hello', IFACE, 

path=PATH, sender_keyword= ' sender ' ) 
self. tube. add_signal_receiver (self . play_signal_cb, 

'Play', IFACE, 

path=PATH, sender_keyword= ' sender ' ) 

def hello_signal_cb ( self , sender=None) : 

"""Somebody Helloed me. World them.""" 
if sender == self . tube . get_unique_name ( ) : 

# sender is my bus name, so ignore my own signal 
return 

logger . debug (' Newcomer %s has joined', sender) 
logger . debug ( 

'Welcoming newcomer and sending them ' 

' the game state ' ) 

self. other = sender 
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# I send my ships and I get theirs in return 
enemy_boats = self . tube . get_obj ect (self . other , 

PATH) . World ( 

self .my_boats , dbus_interf ace=IFACE) 

# I call the callback World, to load the enemy ships 
self . World_cb (enemy_boats) 

def play_signal_cb (self , x, y, sender=None) : 
"""Somebody placed a stone. """ 
if sender == self . tube . get_unique_name ( ) : 
return # sender is my bus name, 
# so ignore my own signal 
logger . debug (' Buddy %s placed a stone at %s x %s ' , 
sender, x, y) 

# Call our Play callback 
self . Play_cb (x, y) 

# In theory, no matter who sent him 

def _list_tubes_error_cb (self , e): 

logger . error (' ListTubes ( ) failed: %s', e) 

def _list_tubes_reply_cb (self , tubes): 
for tube_info in tubes: 

self . _new_tube_cb ( *tube_inf o) 

def _new_tube_cb (self , id, initiator, type, 
service, params, state) : 

logger . debug (' New tube: ID=%d initator=%d ' 
'type=%d service=%s ' 

'params=%r state=%d', id, initiator, ' 
'type, service, params, state) 
if (type == telepathy. TUBE_TYPE_DBUS and 
service == SERVICE) : 

if state == telepathy. TUBE_STATE_LOCAL_PENDING : 
self .tube schan [telepathy . CHANNEL_TYPE_TUBES ] 
.AcceptDBusTube (id) 
self. tube = SugarTubeConnection (self . conn, 

self .tube s_chan [telepathy . CHANNEL_TYPE_TUBES ] 
id, group_iface= 

self . text_chan [telepathy. \ 

CHANNEL_INTERFACE_GROUP] ) 
super (CollaborationWrapper , 

self). init (self. tube, PATH) 

self . tube . watch_participants ( 

self . parti cipant_change_cb) 

def _buddy_j oined_cb (self, activity, buddy) : 
"""Called when a buddy joins the shared 
activity. """ 
logger . debug ( 

'Buddy %s joined', buddy .props . nick) 
if self . buddy_j oined: 

self . buddy_j oined (buddy) 

def _buddy_lef t_cb (self, activity, buddy) : 
"""Called when a buddy leaves the shared 
activity. ' 
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if self . buddy_lef t : 

self . buddy_lef t (buddy) 

def _get_buddy ( self , cs_handle): 

"""Get a Buddy from a channel specific handle.""" 
logger . debug (' Trying to find owner of handle %u...', 

cs_handle) 
group = self . text_chan [telepathy . \ 

CHANNEL_INTERFACE_GROUP] 
my_csh = group . GetSelf Handle ( ) 
logger . debug ( 

'My handle in that group is %u ' , my_csh) 
if my_csh == cs_handle: 

handle = self . conn . GetSelf Handle ( ) 

logger . debug (' CS handle %u belongs to me, %u ' , 
cs_handle, handle) 
elif group . GetGroupFlags ( ) & \ 

telepathy . \ 

CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES: 

handle = group . GetHandleOwners ( [cs_handle] ) [0] 

logger . debug (' CS handle %u belongs to %u', 
cs_handle, handle) 
else : 

handle = cs_handle 

logger . debug (' non-CS handle %u belongs to itself', 
handle) 

# XXX: deal with failure to get the handle owner 

assert handle != 
return self . presence service. \ 

get_buddy_by_telepathy_handle ( 

self. conn. service_name, 

self . conn . obj ect_path, handle) 

Most of the code above is similar to what we've seen in the other examples, and most of 
it can be used as is in any Activity that needs to make D-Bus calls. For this reason we'll 
focus on the code that is specific to using D-Bus. The logical place to start is the HelloO 
method. There is of course nothing magic about the name "Hello". Hello Mesh is 
meant to be a "Hello World" program for using D-Bus Tubes, so by convention the 
words "Hello" and "World" had to be used for something. The HelloO method is 
broadcast to all instances of the Activity to inform them that a new instance is ready to 
receive information about the current state of the shared Activity. Your own Activity 
will probably need something similar, but you should feel free to name it something 
else, and if you're writing the code for a school assignment you should definitely name 
it something else: 

# This is sent to all participants whenever we 

# join an activity 

@signal (dbus_interf ace=IFACE, signature^' ' ) 
def Hello (self) : 

"""Say Hello to whoever else is in the tube.""" 

logger . debug (' I said Hello.') 

def add_hello_handler ( self ) : 

logger . debug (' Adding hello handler.') 
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self . tube . add_signal_receiver ( 
self . hello_signal_cb, 
'Hello', IFACE, 
path=PATH, sender_keyword= ' sender ' ) 



def hello_signal_cb (self , sender=None) : 

"""Somebody Helloed me. World them.""" 
if sender == self . tube . get_unique_name ( ) : 

# sender is my bus name, 

# so ignore my own signal 
return 

logger . debug (' Newcomer %s has joined', sender) 
logger . debug ( 

'Welcoming newcomer and sending them ' 

' the game state ' ) 

self. other = sender 

# I send my ships and I returned theirs 
enemy_boats = self . tube . get_obj ect ( 

self. other, PATH).World( 

self .my_boats , dbus_interf ace=IFACE) 

# I call the callback World, to load the enemy ships 
self . World_cb (enemy_boats) 

The most interesting thing about this code is this line, which Python calls a Decorator: 

Ssignal (dbus_interf ace=IFACE, signature^' ' ) 

When you put ©signal in front of a method name it has the effect of adding the two 
parameters shown to the method call whenever it is invoked, in effect changing it from 
a normal method call to a D-Bus call for a signal. The signature parameter is an empty 
string, indicating that the method call has no parameters. The HelloO method does 
nothing at all locally but when it is received by the other instances of the Activity it 
causes them to execute the WorldO method, which sends back the location of their boats 
and gets the new participants boats in return. 

Batalla Naval is apparently meant to be a demonstration program. Battleship is a game 
for two players, but there is nothing in the code to prevent more players from joining 
and no way to handle it if they do. Ideally you would want code to make only the first 
joiner an actual player and make the rest only spectators. 

Next we'll look at the WorldO method: 

# This is called by whoever receives our Hello signal 

# This method receives the current game state and 

# puts us in sync with the rest of the participants . 

# The current game state is represented by the game 

# object 

Smethod (dbus_interf ace=IFACE, in_signature= ' a (ssiii ) ', 
out signature= ' a (ssiii) ') 
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def World(self, boats): 

"""To be called on the incoming XO after 

they Hello. """ 

if not self. world: 

logger . debug (' Somebody called World on me') 

self. world = True # Instead of loading the world, 

# I am receiving play by play. 

self . World_cb (boats ) 

# now I can World others 

self . add_hello_handler ( ) 
else : 

self. world = True 

logger . debug ( "I ' ve already been welcomed, " 
"doing nothing") 
return self .my_boats 

There is another decorator here, this one converting the WorldO method to a D-Bus call 
for a method. The signature is more interesting than HelloO had. It means an array of 
tuples where each tuple contains two strings and three integers. Each element in the 
array represents one ship and its attributes. World_cb is set to point to a method in 
BatallaNaval.py, (and so is Play_cb). If you study the initi) code in BatallaNaval.py 
you'll see how this happens. WorldO is called in the hello_signal_cb() method we just 
looked at. It is sent to the joiner who sent HelloO to us. 

Finally we'll look at the PlayO signal: 

@ signal (dbus_interf ace=IFACE, signature='ii' ) 

def Play(self, x, y) : 

"""Say Hello to whoever else is in the tube.""" 
logger . debug (' Running remote play:%s x %s.', x, y) 

def add_hello_handler ( self ) : 

self. tube. add_signal_receiver (self . play_signal_cb, 
'Play', IFACE, 
path=PATH, sender_keyword= ' sender ' ) 

def play_signal_cb ( self , x, y, sender=None) : 
"""Somebody placed a stone. """ 
if sender == self . tube . getunique name ( ) : 
return # sender is my bus name, so 
# ignore my own signal 
logger . debug (' Buddy %s placed a stone at %s x %s', 

sender, x, y) 
# Call our Play callback 
self . Play_cb (x, y) 

This is a signal so there is only one signature string, this one indicating that the input 
parameters are two integers. 
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There are several ways you could improve this Activity. When playing against the 
computer in non-sharing mode the game just makes random moves. The game does 
not limit the players to two and make the rest of the joiners spectators. It does not make 
the players take turns. When a player succeeds in sinking all the other players ships 
nothing happens to mark the event. Finally, gettextO is not used for the text strings 
displayed by the Activity so it cannot be translated into languages other than Spanish. 

In the tradition of textbooks everywhere I will leave making these improvements as an 
exercise for the student. 
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1 6 • Adding Text To Speech 



Introduction 

Certainly one of the most popular Activities available is Speak, which takes the words 
you type in and speaks them out loud, at the same time displaying a cartoon face that 
seems to be speaking the words. You might be surprised to learn how little of the code 
in that Activity is used to get the words spoken. If your Activity could benefit from 
having words spoken out loud (the possibilities for educational Activities and games are 
definitely there) this chapter will teach you how to make it happen. 




Hello everyone! 



We Have Ways To Make You Talk 

A couple of ways, actually, and neither one is that painful. They are: 



• Running the espeak program directly 

• Using the gstreamer espeak plugin 
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Both approaches have their advantages. The first one is the one used by Speak. 
(Technically, Speak uses the gstreamer plugin if it is available, and otherwise executes 
espeak directly. For what Speak is doing using the gstreamer plugin isn't really 
needed). Executing espeak is definitely the simplest method, and may be suitable for 
your own Activity. Its big advantage is that you do not need to have the gstreamer 
plugin installed. If your Activity needs to run on something other than the latest 
version of Sugar this will be something to consider. 

The gstreamer plugin is what is used by Read Etexts to do text to speech with 
highlighting. For this application we needed to be able to do things that are not possible 
by just running espeak. For example: 

• We needed to be able to pause and resume speech, because the Activity needs to 
speak a whole page worth of text, not just simple phrases. 

• We needed to highlight the words being spoken as they are spoken. 

You might think that you could achieve these objectives by running espeak on one 
word at a time. If you do, don't feel bad because I thought that too. On a fast computer 
it sounds really awful, like HAL 9000 developing a stutter towards the end of being 
deactivated. On the XO no sounds came out at all. 

Originally Read Etexts used speech-dispatcher to do what the gstreamer plugin does. 
The developers of that program were very helpful in getting the highlighting in Read 
Etexts working, but speech-dispatcher needed to be configured before you could use it 
which was an issue for us. (There is more than one kind of text to speech software 
available and speech-dispatcher supports most of them. This makes configuration files 
inevitable). Aleksey Lim of Sugar Labs came up with the idea of using a gstreamer 
plugin and was the one who wrote it. He also rewrote much of Read Etexts so it would 
use the plugin if it was available, use speech-dispatcher if not, and would not support 
speech if neither was available. 

Running espeak Directly 

You can run the espeak program from the terminal to try out its options. To see what 
options are available for espeak you can use the man command: 

man espeak 

This will give you a manual page describing how to run the program and what options 
are available. The parts of the man page that are most interesting to us are these: 

NAME 

espeak - A multi-lingual software speech synthesizer. 
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SYNOPSIS 

espeak [options] [<words>] 

DESCRIPTION 

espeak is a software speech synthesizer for English, 
and some other languages . 

OPTIONS 

-p <integer> 

Pitch adjustment, to 99, default is 50 

-s <integer> 

Speed in words per minute, default is 160 

-v <voice name> 

Use voice file of this name from 
espeak- data/ voices 

--voices [=<language code>] 

Lists the available voices. If =<language code> 
is present then only those voices which are 
suitable for that language are listed. 

Let's try out some of these options. First let's get a list of Voices: 
espeak --voices 



5 


af 




5 


bs 




5 


ca 




5 


cs 




5 


cy 




5 


de 




5 


el 




5 


en 




5 


en- 


-sc 


2 


en- 


-uk 



■nder VoiceName 


File 


Other 


M afrikaans 


af 




M bosnian 


bs 




M Catalan 


ca 




M czech 


cs 




M welsh-test 


cy 




M german 


de 




M greek 


el 




M default 


default 




M en-scottish 


en/en-sc 


(en 4) 


M english 


en/en 


(en 2) 



. . . and many more . . . 

Now that we know what the names of the voices are we can try them out. How about 
English with a French accent? 

espeak "Your mother was a hamster and your father \ 
smelled of elderberries." -v fr 

Let's try experimenting with rate and pitch: 

espeak "I'm sorry, Dave. I'm afraid I can't \ 
do that." -s 120 -p 30 

The next thing to do is to write some Python code to run espeak. Here is a short 
program adapted from the code in Speak: 

import re 

import subprocess 



155 



PITCH_MAX = 99 
RATE_MAX =99 

PITCH_DEFAULT = PITCH_MAX/2 
RATE_DEFAULT = RATE_MAX/3 

def speak (text, rate=RATE_DEFAULT, pitch=PITCH_DEFAULT, 
voice="def ault" ) : 

# espeak uses 80 to 370 

rate = 80 + (370-80) * int(rate) / 100 

subprocess . call ([ "espeak" , "-p", str (pitch), 
"-s", str (rate), "-v", voice, text], 
stdout=subprocess .PIPE) 

def voices ( ) : 
out = [] 

result = subprocess . Popen ([ "espeak" , "--voices"], 
stdout=subprocess . PIPE) . communicate ( ) [0] 

for line in result . split (' \n ' ) : 
m = re .match ( 

r'\s*\d+\s+([\w-]+)\s+([MF])\s+( [\w_-]+) \s+( .+) 

line) 
if not m: 

continue 
language, gender, name, stuff = m. groups () 
if stuff . startswith (' mb/ ' ) or \ 

name in ( ' en-rhotic ' , ' english_rp ' , 
' english_wmids ' ) : 

# these voices don't produce sound 

continue 
out . append ( (language, name)) 

return out 

def main ( ) : 

print voices ( ) 

speak("I'm afraid I can't do that, Dave.") 
speak ("Your mother was a hamster, and your father " 
+ "smelled of elderberries!", 30, 60, "fr") 

if name == " main " : 

main ( ) 

In the Git repository in the directory Adding TTS this file is named espeak.py. Load 
this file into Eric and do Run Script from the Start menu to run it. In addition to 
hearing speech you should see this text: 
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K'af, 'afrikaans'), ('bs', 'bosnian'), Cca', ' Catalan'), Ccs', ' Czech'), Ccy', 'welsh-test'), Cde', 
'german'), ('el', 'greek'), ('en', 'default'), Cense', 'en-scottish'), ('en-uk', 'english'), Cen-uk- 
north', lancashire'), Cen-us', 'english -us'), Cen-wi', 'en-westindies'), Ceo', 'esperanto'), 
Ces', 'spanish'), Ces-la', 'spanish-latin-american'), Cfi', 'finnish'), Cfr', 'french'), Cfr-be', 
'french'), Cgrc', 'greek-ancient'), Chi', 'hindi-test'), Chr', 'Croatian'), Chu', 'hungarian'), 
Chy', 'armenian'), Chy', 'armenian-west'), ('id', 'indonesian-test'), ('is', 'icelandic-test'), 
('it', 'Italian'), Cku', 'kurdish'), ('la', 'latin'), Civ', 'latvian'), Cmk', 'macedonian-test'), 
CnV, 'dutch-test'), ('no', 'norwegian-test'), ('pi', 'polish'), Cpt', 'brazil'), Cpt-pt', 
'portugal'), Cro', 'romanian'), Cm', 'russian_test'), Csk', 'slovak'), Csq', 'albanian'), Csr', 
'serbian'), Csv', 'swedish'), Csw', 'swahihi-test'), Cta', 'tamil'), Ctr', 'turkish'), Cvi ', 
'vietnam-test'), Czh', 'Mandarin'), ('zh-yue', 'cantonese-test')] 

The voicesO function returns a list of voices as one tuple per voice, and eliminates voices 
from the list that espeak cannot produce on its own. This list of tuples can be used to 
populate a drop down list. 

The speakO function adjusts the value of rate so you can input a value between and 99 
rather than between 80 to 370. speakO is more complex in the Speak Activity than what 
we have here because in that Activity it monitors the spoken audio and generates 
mouth movements based on the amplitude of the voice. Making the face move is most 
of what the Speak Activity does, and since we aren't doing that we need very little code 
to make our Activity speak. 

You can use import espeak to include this file in your own Activities. 

Using The gstreamer espeak Plugin 

The gstreamer espeak plugin can be installed in Fedora 10 or later using Add/Remove 
Software. 
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A simple g streamer plugin to use espeak as a sound 
source. It was developed to simplify trie espeak usage In 
the Sugar Speak activity The plugin uses given text to 
produce audio output. 



Project: 

Group: 

License: 



When you have this done you should be able to download the Read Etexts Activity 
(the real one, not the simplified version we're using for the book) from ASLO and try 
out the Speech tab. You should do that now. It will look something like this: 




is only a record of a pic-nic. it has a purpose, which is to suggest to 
the reader how he would be likely to see Europe and the East 5] he looked 
at them with his own eyes instead of the eyes of those who traveled in 
those countries before him. I make small pretense of showing anyone how 
he ought to look at objects of interest beyond the sea— other books do 
that., and therefore, even if I were competent to do it, there is no need. 

I offer no apologies for any departures from the usual style of 
travel-writing that may be charged against me— for I think I have seen with 
impartial eyes, and I am sure I have written at least honestly, whether 
wisely or not. 

In this volume I have used portions of letters which I wrote for the 
Daily Alta California, of San Francisco, the proprietors of that journal 
having waived their rights and given me the necessary permission. I have 
also inserted portions of several letters written for the Mew York 
Tribune and the Mew York Herald. 

THE AUTHOR. 
SAN FRANCISCO. 



The book used in the earlier screenshots of this manual was Pride and Prejudice by Jane 
Austen. To balance things out the rest of the screen shots will be using The Innocents 
Abroad by Mark Twain. 
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Gstreamer is a framework for multimedia. If you've watched videos on the web you 
are familiar with the concept of streaming media. Instead of downloading a whole song 
or a whole movie clip and then playing it, streaming means the downloading and the 
playing happen at the same time, with the downloading just a bit behind the playing. 
There are many different kinds of media files: MP3's, DivX, WMV, Real Media, and so 
on. For every kind of media file Gstreamer has a plugin. 

Gstreamer makes use of a concept called pipelining. The idea is that the output of one 
program can become the input to another. One way to handle that situation is to put 
the output of the first program into a temporary file and have the second program read 
it. This would mean that the first program would have to finish running before the 
second one could begin. What if you could have both programs run at the same time 
and have the second program read the data as the first one wrote it out? It's possible, 
and the mechanism for getting data from one program to the other is called a pipe. A 
collection of programs joined together in this way is called a pipeline. The program 
that feeds data into a pipe is called a source, and the data that takes the data out of the 
pipe is called a sink. 

The gstreamer espeak plugin uses a simple pipe: text goes into espeak at one end and 
sound comes out the other and is sent to your soundcard. You might think that doesn't 
sound much different from what we were doing before, but it is. When you just run 
espeak the program has to load itself into memory, speak the text you give it into the 
sound card, then unload itself. This is one of the reasons you can't just use espeak a 
word at a time to achieve speech with highlighted words. There is a short lag while the 
program is loading. It isn't that noticeable if you give espeak a complete phrase or 
sentence to speak, but if it happens for every word it is very noticeable. Using the 
gstreamer plugin we can have espeak loaded into memory all the time, just waiting for 
us to send some words into its input pipe. It will speak them and then wait for the next 
batch. 

Since we can control what goes into the pipe it is possible to pause and resume speech. 

The example we'll use here is a version of Read Etexts again, but instead of the 
Activity we're going to modify the standalone version. There is nothing special about 
the gstreamer plugin that makes it only work with Activities. Any Python program can 
use it. I'm only including Text to Speech as a topic in this manual because every Sugar 
installation includes espeak and many Activities could find it useful. 

There is a in our Git repository named speech.py which looks like this: 

import gst 

voice = 'default' 
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pitch = 

rate = -20 
highlight_cb = None 

def _create_pipe ( ) : 

pipeline = 'espeak name=source ! autoaudiosink ' 
pipe = gst . parse_launch (pipeline) 

def stop_cb(bus, message): 

pipe . set_state (gst . STATE_NULL) 

def mark_cb (bus, message) : 

if message . structure . get_name ( ) == ' espeak-mark ' 
mark = message . structure [' mark ' ] 
highlight_cb (int (mark) ) 

bus = pipe . get_bus ( ) 

bus . add_signal_watch ( ) 

bus. connect (' message: : eos ' , stop_cb) 

bus. connect ( 'message: :error' , stop_cb) 

bus. connect ( 'message : : element ' , mark_cb) 

return (pipe . get_by_name (' source ') , pipe) 

def _speech ( source, pipe, words) : 
source . props . pitch = pitch 
source . props . rate = rate 
source . props . voice = voice 
source . props . text = words; 
pipe. set_state (gst . STATE_PLAYING) 

info_source, info_pipe = _create_pipe ( ) 
play_source, play_pipe = _create_pipe ( ) 

# track for marks 

play source . props . track = 2 

def voices ( ) : 

return info source .props . voices 

def say (words) : 

_speech (inf osource, info_pipe, words) 
print words 

def play (words): 

_speech (play_source, play_pipe, words) 

def is_stopped ( ) : 

for i in play_pipe . get_state ( ) : 

if isinstance (i, gst. State) and \ 
i == gst .STATE_NULL: 
return True 
return False 

def stop ( ) : 

play_pipe . set_state (gst . STATE NULL) 
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def is_paused(): 

for i in play_pipe . get_state ( ) : 

if isinstance (i, gst. State) and \ 
i == gst.STATE_PAUSED: 
return True 
return False 

def pause ( ) : 

play_pipe . set_state (gst . STATE_PAUSED) 

def rate_up ( ) : 
global rate 
rate = min(99, rate + 10) 

def rate_down() : 
global rate 
rate = max(-99, rate - 10) 

def pitch_up ( ) : 
global pitch 
pitch = min(99, pitch + 10) 

def pitch_down() : 
global pitch 
pitch = max(-99, pitch - 10) 

def prepare_highlighting (label_text ) : 
i = 
j = 

word_begin = 
word_end = 
current word = 
word_tuples = [] 
omitted = [' ', '\n', u'\r', '_', '[', '{', ']',\ 

' } ', ' I ', '<', '>', '*', ' + ', '/', 'W ] 
omitted_chars = set (omitted) 
while i < len (label_text) : 

if label_text [i] not in omitted_chars : 
word_begin = i 

j = i 

while j < len (label_text ) and \ 

label_text [ j ] not in omitted_chars : 

word_end = j 

i = j 
word_t = (word_begin, word_end, \ 

label_text [word_begin : word_end] . strip () 
if word_t [2] != u'\r' : 

word_tuples . append (word_t ) 
i = i + 1 
return word tuples 

def add_word_marks (word_tuples) : 

"Adds a mark between each word of text." 
i = 

marked_up_text = '<speak> ' 

while i < len (word_tuples ) : 

word_t = word_tuples [ i] 
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marked_up_text = marked_up_text + \ 

'<mark name=" ' + str(i) + '"/>' + word_t[2] 
i = i + 1 
return marked_up_text + '</speak>' 

There is another file named ReadEtextsTTS.py which looks like this: 

import sys 
import os 
import zipfile 
import pygtk 
import gtk 
import getopt 
import pango 
import gobject 
import time 
import speech 

speech_supported = True 

try : 

import gst 

gst . element_f actory_make ( ' e speak ' ) 

print 'speech supported! ' 
except Exception, e: 

speech_supported = False 

print 'speech not supported! ' 

page=0 
PAGE_SIZE =45 

class ReadEtextsActivity ( ) : 

def init (self) : 

"The entry point to the Activity" 

speech . highlight_cb = self . highlight_next_word 

# print speech . voices ( ) 

def highlight_next_word (self , word_count) : 
if word_count <! len (self . word_tuples ) : 

word_tuple = self . word_tuples [word_count ] 

textbuffer = self . textview . get_buf f er ( ) 

tag = textbuffer . createtag ( ) 

tag. set_property ( 'weight ' , pango . WEIGHT_BOLD) 

tag . set_property ( 'foreground', "white") 

tag . set_property ( 'background', "black") 

iterStart = \ 

textbuffer . get_iter_at_of f set (word_tuple [ ] ) 
iterEnd = \ 

textbuffer . get_iter_at_of f set (word_tuple [ 1 ] ) 
bounds = textbuf fer . get_bounds ( ) 

textbuffer. remove_all_tags (bounds [0], bounds [1]) 
textbuf fer . apply_tag (tag, iterStart, iterEnd) 
v_adjustment = \ 

self . scrolled_window . get_vadjustment ( ) 
max = v_adjustment . upper - \ 

v_adjustment .page_size 
max = max * word_count 
max = max / len (self . word_tuples ) 
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v_adjustment . value = max 
return True 

def keypress_cb ( self , widget, event): 

"Respond when the user presses one of the arrow keys" 

global done 

global speech_supported 

keyname = gtk . gdk . keyval_name (event . keyval) 

if keyname == 'KP_End' and speech_supported : 

if speech . is_paused ( ) or speech . is_stopped () : 
speech. play (self. wordsonpage) 

else : 

speech . pause ( ) 

return True 
if keyname == 'plus' : 

self . f ont_increase ( ) 

return True 
if keyname == 'minus' : 

self . f on t_de crease ( ) 

return True 
if speech_supported and speech . is_stopped ( ) == False \ 

and speech . is_paused == False: 

# If speech is in progress, ignore other keys. 

return True 
if keyname == '7': 

speech . pitch_down ( ) 

speech . say (' Pitch Adjusted') 

return True 
if keyname == '8': 

speech . pitch_up ( ) 

speech . say (' Pitch Adjusted') 

return True 
if keyname == '9': 

speech . rate_down ( ) 

speech . say (' Rate Adjusted') 

return True 
if keyname == '0': 

speech . rate_up ( ) 

speech . say (' Rate Adjusted') 

return True 
if keyname == 'KP_Right' : 

self . page_next ( ) 

return True 
if keyname == ' Page_Up ' or keyname == ' KP_Up ' : 

self . page_previous () 

return True 
if keyname == 'KP_Left' : 

self . page_previous () 

return True 
if keyname == ' Page_Down ' or keyname == ' KP_Down ' : 

self . page_next ( ) 

return True 
if keyname == ' Up ' : 

self . scroll_up ( ) 

return True 
if keyname == 'Down' : 

self . scroll_down ( ) 

return True 
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return False 

def page_previous (self ) : 
global page 
page=page-l 
if page < 0: page=0 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . upper - \ 
v_adj ustment .page_size 

def page_next ( self ) : 
global page 
page=page+l 

if page >= len (self .page_index) : page=0 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . lower 

def f ont_decrease (self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size - 1 
if font_size < 1: 
font_size = 1 
self . f ont_desc . set_size ( f ont_size * 1024) 
self .textview . modif y_f ont (self . f ont_desc) 

def f ont_increase (self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size + 1 

self . f ont_desc . set_size ( f ont_size * 1024) 
self. textview .modif y_f ont (self . f ont_desc) 

def scroll_down (self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . upper - 
v_adj ustment .page_size: 
self . page_next () 
return 
if v_adj ustment . value < v_adjustment . upper - 
v_adj ustment .page_size: 
new_value = v_adjustment .value + \ 

v_adjustment . step_increment 
if new_value > v_adjustment . upper - \ 
v_adjustment .page_size : 
new value = v adjustment . upper - \ 
v_adj ustment .page_size 
v adj ustment . value = new value 

def scroll_up ( self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . lower : 

self . page_previous () 

return 
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if v_adjustment . value > v_adjustment . lower : 
new value = v adjustment . value - \ 

v_adj ustment . step_increment 
if new_value < v_adjustment . lower : 

new_value = v_adjustment . lower 
v adj ustment . value = new value 

def show_page ( self , page_number) : 
global PAGE_SIZE, current_word 
position = self . page_index [pagenumber ] 
self . etext_f ile . seek (position) 
linecount = 
label_text = ' ' 

textbuffer = self . textview . get_buf f er ( ) 
while linecount < PAGE_SIZE: 

line = self . etext_f ile . readline ( ) 

label_text = label_text + \ 

Unicode (line, ' iso-885 9-1 ' ) 

linecount = linecount + 1 
textbuffer. set_text (label_text ) 
self. textview. set_buf f er (textbuffer) 
self . word_tuples = \ 

speech . prepare_high lighting (label_text ) 
self . words_on_page = \ 

speech . add_word_marks (self . word_tuples ) 

def save_extracted_f ile (self , zipfile, filename) : 

"Extract the file to a temp directory for viewing" 
filebytes = zipfile . read ( filename) 
f = open("/tmp/" + filename, 'w') 
try : 

f. write (filebytes) 
finally: 

f . close ( ) 

def read_f ile ( self , filename) : 
"Read the Etext file" 
global PAGE_SIZE 

if zipfile . is_zipf ile ( filename) : 

self.zf = zipfile . ZipFile ( filename, 'r') 
self . book_f iles = self . zf . namelist ( ) 
self . save_extracted_f ile (self.zf, \ 

self .book_filesTO] ) 
currentFileName = "/tmp/" + self .book_f iles [ ] 

else : 

currentFileName = filename 

self . etext_f ile = open (currentFileName, "r" ) 

self . page_index = [ ] 

linecount = 

while self . etext_f ile : 

line = self . etext_f ile . readline ( ) 

if not line: 
break 

linecount = linecount + 1 

if linecount >= PAGE_SIZE: 

position = self . etext_f ile . tell ( ) 
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self.page_index. append (position) 
linecount = 
if filename . endswith (". zip" ) : 
os . remove (currentFileName) 

def delete_cb ( self , widget, event, data=None): 
speech . stop ( ) 
return False 

def destroy_cb (self , widget, data=None): 
speech . stop ( ) 
gtk .main_quit () 

def main (self, file_path) : 

self. window = gtk .Window (gtk . WINDOW_TOPLEVEL) 

self. window. connect ( "delete_event" , self . delete_cb) 

self. window. connect ("destroy", self. destroy_cb) 

self . window . set_title ( "Read Etexts Activity") 

self . window . set_size_re quest ( 800 , 600 ) 

self. window. set_border_width (0 ) 

self . read_f ile ( f ile_path) 

self . scrolled_window = gtk . ScrolledWindow ( 

hadjustment=None, vadjustment=None) 
self . textview = gtk . TextView ( ) 
self.textview. set_edi table (False) 
self. textview. set_lef t_margin (50 ) 
self. textview. set_cursor_visible (False) 
self. textview. connect ( "keypressevent" , 

self . keypress_cb) 
self . f ont_desc = pango . FontDescription ( "sans 12") 
self. textview . modif y_f ont (self . f ont_desc) 
self . show_page ( ) 

self . scrolled_window . add (self. textview) 
self. window. add (self . scrolled_window) 
self. textview. show() 
self . scrolled_window . show ( ) 
self.window.show() 
gtk .main ( ) 

if name == " main " : 

try: 

opts, args = getopt . getopt (sys . argv [ 1 : ] , "") 

ReadE texts Activity () .main (args [0]) 
except getopt . error , msg: 

print msg 

print "This program has no options" 

sys . exit (2 ) 

The program ReadEtextsTTS has only a few changes to make it enabled for speech. 
The first one checks for the existence of the gstreamer plugin: 

speech_supported = True 

try : 

import gst 

gst . element_f actory_make ( ' e speak ' ) 

print 'speech supported! ' 
except Exception, e: 
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speech_supported = False 
print 'speech not supported! ' 

This code detects whether the plugin is installed by attempting to import for the Python 
library associated with it named "gst". If the import fails it throws an Exception and we 
catch that Exception and use it to set a variable named speech supported to False. We 
can check the value of this variable in other places in the program to make a program 
that works with Text To Speech if it is available and without it if it is not. Making a 
program work in different environments by doing these kinds of checks is called 
degrading gracefully. Catching exceptions on imports is a common technique in Python 
to achieve this. If you want your Activity to run on older versions of Sugar you may 
find yourself using it. 

The next bit of code we're going to look at highlights a word in the textview and scrolls 
the textview to keep the highlighted word visible. 

class ReadEtextsActivity ( ) : 

def init (self): 

"The entry point to the Activity" 

speech . highlight_cb = self . highlight_next_word 

# print speech . voices ( ) 

def highlight_next_word (self , word_count) : 
if word_count < len (self . word_tuples ) : 

word_tuple = self . word_tuples [word_count ] 

textbuffer = self . textview . get_buffer ( ) 

tag = textbuf f er . create_tag ( ) 

tag. set_property ( 'weight ' , pango . WEIGHT_BOLD) 

tag . set_property ( 'foreground', "white") 

tag . set_property ( 'background', "black") 

iterStart = \ 

textbuffer. get_iter_at_of f set (word_tuple [ ] ) 
iterEnd = \ 

textbuffer. get_iter_at_of f set (word_tuple [ 1 ] ) 
bounds = textbuf fer . get_bounds ( ) 

textbuffer. remove_all_tags (bounds [0], bounds [1]) 
textbuf fer . apply_tag (tag, iterStart, iterEnd) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
max = v adj ustment . upper - v adjustment .page size 
max = max * word_count 
max = max / len (self . word_tuples ) 
v_adj ustment . value = max 
return True 

In the init method we assign a variable called highlight _cb in speech.py with a 

method called highlight_next_word(). This gives speech.py a way to call that method 
every time a new word in the textview needs to be highlighted. 
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The next line will print the list of tuples containing Voice names to the terminal if you 
uncomment it. We aren't letting the user change voices in this application but it would 
not be difficult to add that feature. 

The code for the method that highlights the words follows. What it does is look in a list 
of tuples that contain the starting and ending offsets of every word in the textarea's text 
buffer. The caller of this method passes in a word number (for instance the first word in 
the buffer is word 0, the second is word 1, and so on). The method looks up that entry 
in the list, gets its starting and ending offsets, removes any previous highlighting, then 
highlights the new text. In addition to that it figures out what fraction of the total 
number of words the current word is and scrolls the textviewer enough to make sure 
that word is visible. 

Of course this method works best on pages without many blank lines, which fortunately 
is most pages. It does not work so well on title pages. An experienced programmer 
could probably come up with a more elegant and reliable way of doing this scrolling. 
Let me know what you come up with. 

Further down we see the code that gets the keystrokes the user enters and does speech- 
related things with them: 

def keypress_cb (self , widget, event): 

"Respond when the user presses one of the arrow keys" 

global done 

global speech_supported 

keyname = gtk . gdk . keyval_name (event . keyval) 

if keyname == 'KP_End' and speech_supported: 

if speech . is_paused ( ) or speech . is_stopped () : 
speech. play (self. words_on_page) 

else : 

speech .pause ( ) 

return True 
if speech_supported and speech . is_stopped ( ) == False \ 

and speech . is_paused == False: 

# If speech is in progress, ignore other keys. 

return True 
if keyname == '7': 

speech .pitch_down ( ) 

speech . say (' Pitch Adjusted') 

return True 
if keyname == ' 8 ' : 

speech .pitch_up ( ) 

speech . say (' Pitch Adjusted') 

return True 
if keyname == ' 9 ' : 

speech . rate_down ( ) 

speech . say (' Rate Adjusted') 

return True 
if keyname == ' ' : 

speech . rate_up ( ) 

speech . say (' Rate Adjusted') 
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return True 

As you can see, the functions we're calling are all in the file speech.py that we 
imported. You don't have to fully understand how these functions work to make use of 
them in your own Activities. Notice that the code as written prevents the user from 
changing pitch or rate while speech is in progress. Notice also that there are two 
different methods in speech.py for doing speech. playO is the method for doing text to 
speech with word highlighting. say() is for saying short phrases produced by the user 
interface, in this case "Pitch adjusted" and "Rate adjusted". Of course if you put code 
like this in your Activity you would use the _() function so these phrases could be 
translated into other languages. 

There is one more bit of code we need to do text to speech with highlighting: we need to 
prepare the words to be spoken to be highlighted in the textviewer. 

def show_page ( self , page_number ) : 
global PAGE_SIZE, current_word 
position = self . page_index [pagenumber ] 
self . etext_f ile . seek (position) 
linecount = 
label_text = ' ' 

textbuffer = self . textview . get_buf f er ( ) 
while linecount < PAGE_SIZE: 

line = self . etext_f ile . readline ( ) 

label_text = label_text + Unicode (line, \ 
'iso-8859-1' ) 

linecount = linecount + 1 
textbuffer. set_text (label_text ) 
self. textview. set_buf f er (textbuffer) 
self . word_tuples = \ 

speech . prepare_high lighting (label_text ) 
self . words_on_page = \ 

speech . add_word_marks (self . word_tuples ) 

The beginning of this method reads a page's worth of text into a string called label_text 
and puts it into the textview's buffer. The last two lines splits the text into words, 
leaving in punctuation, and puts each word and its beginning and ending offsets into a 
tuple. The tuples are added to a List. 

speech.add_word_marks() converts the words in the List to a document in SSML 
(Speech Synthesis Markup Language) format. SSML is a standard for adding tags (sort 
of like the tags used to make web pages) to text to tell speech software what to do with 
the text. We're just using a very small part of this standard to produce a marked up 
document with a mark between each word, like this: 

<speak> 

<mark name=" " />The<mark name=" 1 " />quick<mark name-"2"/> 

brown<mark name="3"/>f ox<mark name="4 "/> jumps 
</speak> 
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When espeak reads this file it will do a callback into our program every time it reads one 
of the mark tags. The callback will contain the number of the word in the word_tuples 
List which it will get from the name attribute of the mark tag. In this way the method 
being called will know which word to highlight. The advantage of using the mark name 
rather than just highlighting the next word in the textviewer is that if espeak should fail 
to do one of the callbacks the highlighting won't be thrown out of sync. This was a 
problem with speech-dispatcher. 

A callback is just what it sounds like. When one program calls another program it can 
pass in a function or method of its own that it wants the second program to call when 
something happens. 

To try out the new program run 

. /ReadEtextsTTS .py bookfile 

from the Terminal. You can adjust pitch and rate up and down using the keys 7, 8, 9, 
and on the top row of the keyboard. It should say "Pitch Adjusted" or "Rate 
Adjusted" when you do that. You can start, pause, and resume speech with 
highlighting by using the End key on the keypad. (On the XO laptop the "game" keys 
are mapped to what is the numeric keypad on a normal keyboard. This makes these 
keys handy for use when the XO is folded into tablet mode and the keyboard is not 
available). You cannot change pitch or rate while speech is in progress. Attempts to do 
that will be ignored. The program in action looks like this: 
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Alexandria, which will be reached in twenty-four hours. The ruins 
of Caesar's Palace, Pompey's Pillar. Cleopatra's Needle, the 
Catacombs, and ruins of arc: em Alexandria mill be found worth the 
visit. The journey to Cairo, one hundred and thirty miles by rail, 
can be made in a lew hours, and from which can be visited the site 
of ancient Memphis, Joseph's Granaries, and the Pyramids. 

From Alexandria the route will be taken homeward, calling at 
Malta, f^!TT?^ {in Sardinia), and Raima {in Majorca), all 
magnificent harbors, with charming scenery, and abounding in fruits. 

A day or two will be spent at each place, and leaving Parma in the 
evening, Valencia in 'jpain will be reached the next morning. A few 
days will be spent in this, the finest city of Spain, 

From Valencia, the homeward course will be continued, skirting 
along the coast of Spain, Alicant, Carthagena, Palos, and Malaga 
will be passed but a mile or two dtstant. and Gibraltar reached in 
about twenty-four hours. 

A stay of one day will bo made here, and the voyage continued to 
Madeira, which will be reached in about three days. Captain 
Marryatt writes: "I do not know a spot on the globe which so much 
astonishes and delights upon first arrival as Madeira." A stay of 
one or two days will be made here, which, if time permits, may be 
fix-tended, and passing on through the islands, and probably in sight 
of the Peak of "leneriffe, a southern track will be taken, and the 
Atlantic crossed within the latitudes of the northeast trade winds, 
where mild and pleasant weather, and a smooth sea, can always be 
expected. 

A call will be made at Bermuda, which Sies directly in this route 



_ 



^L 



. 



That brings us to the end of the topic of Text to Speech. If you're like to see more, the 
Git repository for this book has a few more sample programs that use the gstreamer 
espeak plugin. These examples were created by the author of the plugin and 
demonstrate some other ways you can use it. There's even a "choir" program that 
demonstrates multiple voices speaking at the same time. 
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17. Fun With The Journal 

Introduction 

By default every Activity creates and reads one Journal entry. Most Activities don't 
need to do any more with the Journal than that, and if your Activity is like that you 
won't need the information in this chapter. Chances are that someday you will want to 
do more than that, so if you do keep reading. 

First let's review what the Journal is. The Journal is a collection of files that each have 
metadata (data about data) associated with them. Metadata is stored as text strings and 
includes such things as the Title, Description, Tags, MIME Type, and a screen shot of 
the Activity when it was last used. 

Your Activity cannot read and write these files directly. Instead Sugar provides an API 
(Application Programming Interface) that gives you an indirect way to add, delete and 
modify entries in the Journal, as well as a way to search Journal entries and make a list 
of entries that meet the search criteria. 

The API we'll use is in the datastore package. After version .82 of Sugar this API was 
rewritten, so we'll need to learn how to support both versions in the same Activity. 

If you've read this far you've seen several examples where Sugar started out doing one 
thing and then changed to do the same thing a better way but still provided a way to 
create Activities that would work with either the old or the new way. You may be 
wondering if it is normal for a project to do this. As a professional programmer I can tell 
you that doing tricks like this to maintain backward compatibility is extremely common, 
and Sugar does no more of this than any other project. There are decisions made by 
Herman Hollerith when he tabulated the 1890 census using punched cards that 
computer programmers must live with to this day. 

Introducing Sugar Commander 

I am a big fan of the concept of the Journal but not so much of the Journal Activity that 
Sugar uses to navigate through it and maintain it. My biggest gripe against it is that it 
represents the contents of thumb drives and SD cards as if the files on these were also 
Journal entries. My feeling is that files and directories are one thing and the Journal is 
another, and the user interface should recognize that. 
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Strictly speaking the Journal Activity is and is not an Activity. It inherits code from the 
Activity class just like any other Activity, and it is written in Python and uses the same 
datastore API that other Activities use. However, it is run in a special way that gives it 
powers and abilities far beyond those of an ordinary Activity. In particular it can do two 
things: 

• It can write to files on external media like thumb drives and SD cards. 

• It alone can be used to resume Journal entries using other Activities. 

While I would like to write a Journal Activity that does everything the original does but 
has a user interface more to my own taste the Sugar security model won't allow that. 
Recently I came to the conclusion that a more mild-mannered version of the Journal 
Activity might be useful. Just as Kal-El sometimes finds it more useful to be Qark Kent 
than Superman, my own Activity might be a worthy alternative to the built-in Journal 
Activity when super powers are not needed. 

My Activity, which I call Sugar Commander, has two tabs. One represents the Journal 
and looks like this: 



Journal Files 



Ttie_Creatjre5_of_Man by Howard L. Myers 

Short stones by an underrated science fiction author 
vuho died in the 1970's. Free RTF from the Baen Free 
Description Library. 



■Howard L. Myers, Science fiction 



Title 


v MIME 


The Angel of the Revolution, by George Griffith 


application^ 


The_creatures_of_Man by Howard L, Myers i. 


application/rtf 


The Emerald City of Oz. by L Frank Baurn pio 


application/zip 


The Hound of the Baskervilles, by K conan Doyle P4 


application/zip 


The Island of Doctor Moreau. by H. C. Wells P?7 


application^ 


The Jupiter weapon, by Charles Louis Fontenay 


application/pdf 


The Mummy and Miss Nitocris, by George Griffith P8 


application^ 


The Niaht Life of the Gods, bv Thome Smith P7 


aDDlcationftn 



This tab lets you browse through the Journal sorted by Title or MIME Type, select 
entries and view their details, update Title, Description or Tags, and delete entries you 
no longer want. The other tab shows files and folders and looks like this: 
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-■' CB M 1D2F-3F2F 

Location: sugarcornmander-l.xo 




@ Recently Used 

£j Desktop 
O File System 
Q 198 GB Filesystem 
Q 515 MB Filesystem 
Q30G6 pilesystem 
£j Documents 
£j Music 
^j Pictures 
' Videos 




Creating Sugar Activities, odt 
2| GetlAE.ooks-5.K0 
[3 LeerPendnve-l.xo 
^ ReadETexts-lS.xu 
[3 SugarCommander-l.xo 
Q svnz-Ol.xo 
Q ViewSlides-ll.xo 



12/20/2009 

03/15^2010 

03/16/2010 

03/08/2010 

Vesterday at 23:53 

15:47 

03/13/2010 



Copy File to The Journal 



This tab lets you browse through the files and folders or the regular file system, 
including thumb drives and SD cards. You can select a file and make a Journal entry 
out of it by pushing the button at the bottom of the screen. 

This Activity has very little code and still manages to do everything an ordinary 
Activity can do with the Journal. You can download the Git repository using this 
command: 

git clone git : //git . sugarlabs . org/sugar-commander/\ 
mainline . git 

There is only one source file, sugarcommander.py: 

import logging 

import os 

import gtk 

import pango 

import zipfile 

from sugar import mime 

from sugar . activity import activity 

from sugar . datastore import datastore 

from sugar . graphics . alert import NotifyAlert 

from sugar . graphics import style 

from gettext import gettext as _ 

import gobject 

import dbus 

COLUMN_TITLE = 
COLUMN MIME = 1 
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COLUMN_JOBJECT = 2 

DS_DBUS_SERVICE = ' org . laptop . sugar . DataStore ' 
DS_DBUS_INTERFACE = ' org . laptop . sugar . DataStore ' 
DS_DBUS_PATH = ' /org/laptop/sugar /DataStore ' 

_logger = logging . getLogger (' sugar-commander ' ) 

class SugarCommander (activity .Activity) : 

def init (self, handle, create_j ob j ect=True) : 

"The entry point to the Activity" 

activity .Activity . init (self, handle, False) 

self . selected_j ournal_entry = None 
self . selected_path = None 

canvas = gtk . Notebook ( ) 
canvas . props . show_border = True 
canvas . props . show_tabs = True 
canvas . show ( ) 

self . ls_j ournal = gtk . ListStore ( 

gob j ect . TYPE_STRING, 

gob j ect . TYPE_STRING, 

gob j ect . TYPE_PYOB JECT) 
self . tv_j ournal = gtk . TreeView (self . ls_j ournal) 
self . tv j ournal . set_rules_hint (True) 
self. tv_ journal . set_search_column (COLUMN_TITLE) 
self . selection_j ournal = \ 

self . tv_j ournal . get_se lection ( ) 
self . select ion_j ournal . set mode ( 

gtk. SELECTION_SINGLE) 
self . select ion_j ournal. connect ("changed", 

self . select ion_j ournal_cb) 
renderer = gtk . CellRendererText ( ) 

renderer . set_property ( ' wrap-mode ' , gtk . WRAP_WORD) 
renderer . set_property ('wrap -width', 500) 
renderer . set_property ('width', 500) 
self . col_j ournal = gtk . TreeViewColumn (_(' Title ') , 

renderer, text=COLUMN_TITLE) 
self. co 1_ journal . set_sort_column_id (COLUMN_TITLE) 
self . tv j ournal . append_column ( self. col_j ournal) 

mime_renderer = gtk . CellRendererText ( ) 
mime_renderer . set_property ('width', 500) 
self . col_mime = gtk . TreeViewColumn (_(' MIME ') , 

mime_renderer, text=COLUMN_MIME) 
self . col_mime . set_sort_column_id (COLUMN_MIME) 
self . tv_j ournal . append_column (self . col_mime) 

self . list_scroller_j ournal = gtk . ScrolledWindow ( 
hadjustment=None, vadjustment=None) 

self . list_scroller_j ournal . set_policy ( 

gtk. POLICY_AUTOMATIC, gtk . POLICY_AUTOMATIC ) 

self . list_scroller_j ournal . add (self . tv j ournal) 

label_attributes = pango . AttrList ( ) 
label__attributes .insert (pango . AttrSize ( 
14000, 0, -1)) 
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label_attributes .insert (pango. At tr Fore ground ( 
65535, 65535, 65535, 0, -1)) 

tabl_label = gtk . Label (_( "Journal" ) ) 

tabl_label . set_at tributes (label_at tributes ) 

tabl_label . show ( ) 

self . tv j ournal.show() 

self . list_scroller_j ournal.show() 

column_table = gtk . Table (rows=l , columns=2, 
homogeneous = False) 

image_table = gtk . Table (rows=2 , columns=2, 

homogeneous=False) 
self. image = gtk. Image () 
image_table . attach (self . image, 0, 2, 0, 1, 

xoptions=gtk.FILL | gtk. SHRINK, 

yoptions=gtk.FILL | gtk. SHRINK, 

xpadding=10 , 

ypadding=10 ) 

self . btn_save = gtk . Button (_( "Save" ) ) 

self . btn_save .connect ( ' button_press_event ' , 

self . save_button_press_event_cb) 
image_table . attach (self .btn_save, 0, 1, 1, 2, 

xoptions=gtk. SHRINK, 

yoptions=gtk . SHRINK, xpadding=10 , 

ypadding=10 ) 
self . btn_save .props . sensitive = False 
self . btn_save . show ( ) 

self . btn_delete = gtk. Button (_ ("Delete" ) ) 
self . btn_delete .connect ( ' button_press_event ' , 

self . delete_button_press_event_cb) 
image_table . attach (self .btn_delete, 1, 2, 1, 2, 

xoptions=gtk. SHRINK, 

yoptions=gtk . SHRINK, xpadding=10 , 



ypadding=10 ) 



ypadding=iu ) 
self . btn_delete .props . sensitive = False 

self.btn Hplptp.Rhnw/1 



self . btn_delete .show 



column_table . attach (image_table, 0, 1, 0, 1, 
xoptions=gtk.FILL | gtk. SHRINK, 
yoptions=gtk . SHRINK, xpadding=10, 
ypadding=10 ) 

entry_table = gtk . Table (rows=3 , columns=2, 
homogeneous=False) 

title_label = gtk. Label (_( "Title" ) ) 

entry_table . attach (title_label , 0, 1, 0, 1, 

xoptions=gtk. SHRINK, 

yoptions=gtk. SHRINK, 

xpadding=10, ypadding=10) 
title_label . show ( ) 

self . title_entry = gtk . Entry (max=0 ) 

entry_table . attach (self . title_entry, 1, 2, 0, 1, 
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xop t ion s=gtk. FILL | gtk. SHRINK, 

yoptions=gtk . SHRINK, xpadding=10 , ypadding=10 ) 
self . title entry . connect ( ' key_press_event ' , 

self . key_press_event_cb) 
self . title_entry . show ( ) 

description_label = gtk . Label (_( "Description" ) ) 
entry_table . attach (description_label, 0, 1, 1, 2, 

xop ti on s=gtk. SHRINK, 
yoptions=gtk. SHRINK, 
xpadding=10, ypadding=10) 
description_label . show ( ) 

self . description_textview = gtk . TextView ( ) 
self . description_textview . set_wrap_mode ( 

gtk.WRAP_WORD) 
entry_table .attach (self. description_textview, 

1, 2, 1, 2, 

xoptions=gtk. EXPAND | gtk. FILL | gtk. SHRINK, 

yoptions=gtk. EXPAND | gtk. FILL | gtk. SHRINK, 

xpadding=10, ypadding=10) 
self . description_textview .props . accepts_tab = False 
self . description_textview . connect ( ' key_press_event ' , 

self . key_press_event_cb) 
self . description_textview . show ( ) 

tags_label = gtk . Label (_( "Tags" ) ) 
entry_table . attach (tags_label, 0, 1, 2, 3, 

xoptions=gtk. SHRINK, 

yoptions=gtk. SHRINK, 

xpadding=10, ypadding=10) 
tags_label . show ( ) 

self . tags_textview = gtk . TextView ( ) 

self . tags_textview . set_wrap_mode (gtk . WRAP_WORD) 

entry_table . attach (self . tagstextview, 1, 2, 2, 3, 

xoptions=gtk .FILL, 

yop t ion s=gtk. EXPAND | gtk. FILL, 

xpadding=10, ypadding=10) 
self . tags_textview .props . accepts_tab = False 
self . tags_textview .connect ( ' key_press_event ' , 

self . key_press_event_cb) 
self . tags_textview . show ( ) 

entry_table . show ( ) 

self . scroller_entry = gtk . ScrolledWindow ( 

hadjustment=None, vadjustment=None) 
self. scroller_entry. set_policy (gtk. POLICY_NEVER, 

gtk. POLICY_AUTOMATIC) 
self . scroller_entry . add_with_viewport (entry_table) 
self . scroller_entry . show ( ) 

column_table .attach (self. scroller_entry, 
1, 2, 0, 1, 

xop t ion s=gtk. FILL | gt k. EXPAND | gtk. SHRINK, 
yop t ion s=gtk. FILL | gt k. EXPAND | gtk. SHRINK, 
xpadding=10, ypadding=10) 
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image_table . show ( ) 
column_table . show ( ) 

vbox = gtk.VBox (homogeneous=True, spacing=5) 

vbox . pack_start (column_table) 

vbox . pack_end (self . list_scroller_j ournal) 

canvas . append_page (vbox, tabl_label) 

self . _f ilechooser = gtk . FileChooserWidget ( 

action=gtk.FILE_CHOOSER_ACTION_OPEN, 

backend=None) 
self._filechooser. s e t_curr en t f older ( " /media" ) 
self . copy_button = gtk.Button( 

_("Copy File To The Journal")) 
self . copy_button . connect ( ' clicked' , 

self.create_j ournal_entry) 
self . copy_button . show ( ) 

self._filechooser. set_extra_widget (self . copy_button) 
preview = gtk. Image () 

self._filechooser. set_preview_widget (preview) 
self. _filechooser. connect ( "update -pre view" , 

self .update preview cb, preview) 
tab2_label = gtk . Label (_( "Files" ) ) 
tab2_label . set_at tributes (label_at tributes ) 
tab2_label . show ( ) 
canvas . append_page (self._filechooser, tab2_label) 

self . set_canvas (canvas) 
self . show_all ( ) 

toolbox = activity . ActivityToolbox (self ) 
activity_toolbar = toolbox . get_activity_toolbar ( ) 
activity_toolbar . keep .props .visible = False 
activity_toolbar . share .props .visible = False 
self . set_toolbox (toolbox) 
toolbox . show ( ) 

self . load_j ournal_table ( ) 

bus = dbus . SessionBus ( ) 
remote_ob j ect = bus . get_ob j ect ( 

DS_DBUS_SERVICE, DS_DBUS_PATH) 
_datastore = dbus . Interface (remote_obj ect , 

DS_DBUS_INTERFACE) 
_data store . connect_to_signal (' Created ' , 

self . datastore_created_cb) 
_data store . connect_to_signal ( 'Updated ' , 

self . datastore_updated_cb) 
_data store . connect_to_signal (' Deleted ' , 

self . datastore_deleted_cb) 

self . selected_j ournal_entry = None 

def update_preview_cb (self , f ile_chooser , preview) : 
filename = f ile_chooser . get_preview_f ilename ( ) 
try : 

f ile_mimetype = mime . get_for_file (filename) 
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if f ile_mimetype . startswith (' image/ ' ) : 
pixbuf = \ 

gtk . gdk . pixbuf _new_from_f ile_at_size ( 
filename, 

style . zoom (320 ) , style . zoom (240 ) ) 
preview. set from pixbuf (pixbuf ) 
have preview = True 
elif f ile_mimetype == ' application/x-cbz ' : 
fname = self . extract_image (filename) 
pixbuf = \ 

gtk . gdk . pixbuf _new_f rom_f ile_at_size ( 
fname, 

style . zoom (320 ) , style . zoom (240 ) ) 
preview. set_f rom_pixbuf (pixbuf) 
have preview = True 
os . remove ( fname) 
else : 

havepreview = False 
except : 

have_preview = False 
f ile_chooser . set_preview_widget_active ( 

have preview) 
return 

def key_press_event_cb (self , entry, event): 
self . btn_save . props . sensitive = True 

def save_button_press_event_cb (self , entry, event): 
self . update_entry ( ) 

def delete_button_press_event_cb (self , entry, event): 
da tastore. delete ( 

self . selected_j ournal_entry . ob j ect_id) 

def datastore_created_cb (self , uid) : 
new_jobject = datastore . get (uid) 
iter = self . ls_j ournal . append ( ) 
title = new_j obj ect .metadata [' title ' ] 
self .ls_j ournal. set (iter, COLUMN_TITLE, title) 
mime = new_j obj ect .metadata [' mime_type ' ] 
self . ls_journal . set (iter, COLUMN_MIME, mime) 
self . ls_ journal. set (iter, COLUMN_JOBJECT, 
new_j obj ect) 

def datastore_updated_cb (self , uid): 
new_jobject = datastore . get (uid) 
iter = self . ls_j ournal . get_iter_f irst ( ) 
for row in self . ls_j ournal : 

j Obj ect = row[COLUMN_JOBJECT] 
if j ob j ect . ob j ect_id == uid: 

title = new_j obj ect .metadata [' title ' ] 
self . ls_j ournal . set_value (iter, 

COLUMN_TITLE, title) 
break 
iter = self . ls_j ournal . iter_next (iter ) 
object_id = self . selected_j ournal_entry . obj ect_id 
if object_id == uid: 

self . set_f orm_f ields (new_j obj ect ) 
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def datastore_deleted_cb (self , uid) : 
save_path = self . selected_path 
iter = self . ls_j ournal . get_iter_f irst ( ) 
for row in self. Is journal: 

jobject = row[COLUMN_JOBJECT] 
if j ob j ect . ob j ect_id == uid: 

self.ls_journal. remove (iter) 
break 
iter = self . ls_j ournal . iter_next (iter ) 

try: 

self . select ion_j ournal . select_path (save_path) 

self . tv_j ournal . grab_f ocus ( ) 
except : 

self . title_entry . set_text ( ' ' ) 

description_textbuf f er = \ 

self . description_textview . get_buf f er ( ) 

description_textbuf f er . set_text ( ' ' ) 

tags_textbuf f er = \ 

self.tags_textview. get_buf f er ( ) 

tags_textbuf f er . set_text ( ' ' ) 

self . btn_save .props . sensitive = False 

self . btn_delete .props . sensitive = False 

self . image . clear ( ) 

self . image . show ( ) 

def update_entry (self ) : 
needs_update = False 

if self . selected_j ournal_entry is None: 
return 

object_id = self . selected_j ournal_entry . obj ect_id 
jobject = datastore . get (ob j ect_id) 

old_title = j obj ect .metadata . get (' title ' , None) 
if old_title != self . title_entry .props . text : 

j obj ect .metadata [' title ' ] = \ 

self . title_entry .props. text 

jobject .metadata [' title_set_by_user ' ] = '1' 

needs_update = True 

old_tags = j obj ect .metadata . get (' tags ' , None) 
new_tags = \ 

self . tags_textview .props .buffer. props .text 
if old_tags != newtags: 

j obj ect .metadata [' tags ' ] = new_tags 

needs_update = True 

old_description = j obj ect .metadata . get ( 

'description', None) 
new_description = \ 

self . description_textview .props .buffer .props . text 
if old_description != new_description : 

j obj ect .metadata [' description ' ] = new_description 

needs_update = True 
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if needs_update : 

da tastore. write (jobject, update_mtime=False, 
reply_handler=self . datastore_write_cb, 
error_handler=self . datastore_write_error_cb) 

self . btn_save . props . sensitive = False 

def datastore_write_cb (self ) : 
pass 

def datastore_write_error_cb (self , error) : 
logging. error ( 

' sugarcommander . datastore_write_error_cb : ' 
;r ' % error) 



I o, i o. 



def close (self, skip_save=False) : 

"Override the close method so we don't try to 

create a Journal entry." 

activity .Activity . close (self, True) 

def selection_j ournal_cb (self , selection): 

self . btn_delete . props . sensitive = True 

tv = selection . get_tree_view ( ) 

model = tv . get_model ( ) 

sel = selection . get_selected ( ) 

if sel: 

model, iter = sel 

jobject = model. getvalue (iter, COLUMN_JOBJECT) 

jobject = datastore . get (j obj ect . obj ect_id) 

self . selected_j ournal_entry = jobject 

self . set_f orm_f ields ( j ob j ect ) 

self . selected_path = model . get_path (iter ) 

def set_form_f ields ( self , jobject): 

self . title_entry . set_text (jobject.metadata[ 'title' ] ) 
description_textbuf f er = \ 

self . description_textview . get_buf f er ( ) 
if j obj ect .metadata . has_key (' description ' ) : 

description_textbuf f er . set_text ( 

jobject. metadata! 'description' ] ) 
else : 

description_textbuf f er . set_text ( ' ' ) 
tags_textbuf f er = self . tags_textview . get_buf f er ( ) 
if j obj ect .metadata . has_key (' tags ' ) : 

tags_textbuf f er . set_text (jobject.metadata[ 'tags' ] ) 
else : 

tags_textbuf f er . set_text ( ' ' ) 
self . create_preview (j obj ect . obj ect_id) 

def create_preview ( self , object_id): 
jobject = datastore . get (obj ect_id) 

if j obj ect .metadata . has_key (' preview ' ) : 
preview = j obj ect .metadata [' preview ' ] 
if preview is None or preview == ' ' \ 
or preview == 'None' : 

if jobject.metadataf' mime_type ' ] . startswith ( 
' image/ ' ) : 
filename = j ob j ect . get_f ile_path ( ) 
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self . show_image (filename) 
return 
if j object .metadata [ 'mime_type ' ] == \ 
' application/x-cbz ' : 
filename = j ob j ect . get_f ile_path ( ) 
fname = self . extract_image (filename) 
self . show_image (fname) 
os . remove ( fname) 
return 

if j obj ect .metadata . has_key (' preview ' ) and \ 
len (j obj ect .metadata [' preview '] ) > 4: 

if jobject .metadata [ 'preview' ][ 1 : 4 ] == 'PNG': 

preview_data = j obj ect . metadata [' preview ' ] 
else : 

import base64 
preview data = \ 

base 64 . b64 decode ( 

j obj ect .metadata [ 'preview ' ] ) 

loader = gtk . gdk . Pixbuf Loader ( ) 
loader. write (preview_data) 
scaled_buf = loader . get_pixbuf ( ) 
loader . close ( ) 

self . image . set_f rom_pixbuf (scaled_buf ) 
self . image . show ( ) 
else : 

self . image . clear ( ) 
self . image . show ( ) 

def load_j ournal_table (self ) : 

self . btn_save .props . sensitive = False 
self . btn_delete .props . sensitive = False 
ds_mounts = datastore .mounts ( ) 
mountpoint_id = None 
if len (ds_mounts ) == 1 and \ 
ds_mounts [0] [ ' id' ] == 1: 
pass 
else : 

for mountpoint in ds_mounts : 
id = mountpoint [' id' ] 
uri = mountpoint [' uri ' ] 
if uri . startswith (' /home ' ) : 
mountpoint_id = id 

query = { } 

if mountpoint_id is not None: 

query [ 'mountpoints ' ] = [ mountpoint_id ] 
ds_objects, num_objects = \ 

datastore. find( query, properties=[ ' uid ' , 

'title', ' mime_type ' ] ) 

self . ls_j ournal. clear () 

for i in xrange (0, num_objects, 1) : 
iter = self . ls_j ournal . append ( ) 
title = ds_obj ects [ i] .metadata [' title ' ] 
self .ls_journal. set (iter, COLUMN_TITLE, title) 
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mime = ds_obj ects [ i] .metadata [' mime_type ' ] 
self . ls_journal . set (iter, COLUMN_MIME, mime) 
self .ls_ journal. set (iter, COLUMN_JOBJECT, 

ds_ob j ects [i] ) 
if not self . selected_j ournal_entry is None and \ 

self . selected_j ournal_entry . ob j ect_id == \ 

ds_ob j ects [i] .object_id: 

self . select ion_j ournal . select_iter (iter) 

self. ls_ journal . set_sort_column_id (COLUMN_TITLE, 

gtk. SORT_ASCENDING) 
v_adjustment = \ 

self . list_scroller_j ournal . get_vadjustment ( ) 
v_adjustment . value = 
return ds_ob j ects [ ] 

def create_j ournal_entry (self , widget, data=None): 
filename = self . _f ilechooser . get_f ilename ( ) 
j ournal_entry = datastore . create ( ) 
j ournal_entry. metadata [' title ' ] = \ 

self . make_new_f ilename ( filename) 
j ournal_entry. metadata [' title_set_by_user ' ] = '1' 
j ournal_entry . metadata [' keep ' ] = '0' 
f ile_mimetype = mime . get_for_file ( filename) 
if not f ile_mimetype is None: 

j ournal_entry .metadata [' mime_type ' ] = \ 
f ile^mimetype 
j ournal_entry. metadata [' buddies ' ] = ' ' 
if f ile_mimetype . startswith (' image/ ' ) : 

preview = \ 

self . create_preview_metadata (filename) 
elif f ile_mimetype == ' application/x-cbz ' : 

fname = self . extractimage ( filename) 

preview = self . create_preview_metadata (fname) 

os . remove ( fname) 
else : 

preview = ' ' 
if not preview == ' ' : 

j ournal_entry. metadata [' preview ' ] = \ 

dbus . ByteArray (preview) 
else : 

j ournal_entry .metadata [' preview ' ] = ' ' 

j ournal_entry . f ile_path = filename 
datastore . write ( j ournal_entry) 

self . alert (_(' Success ') , _('%s added to Journal.') 
% self . make_new_f ilename (filename) ) 

def alert (self, title, text=None) : 
alert = Notif yAlert (timeout=20 ) 
alert . props . title = title 
alert . props .msg = text 
self . add_alert (alert) 

alert. connect ('response', self. alert_cancel_cb) 
alert . show ( ) 

def alert_cancel_cb ( self , alert, response_id) : 
self. remove alert (alert) 
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def show_image (self , filename) : 

"display a resized image in a preview" 

scaled_buf = gtk . gdk .pixbuf_new_f rom_f ile_at_size ( 

filename, 

style . zoom (320 ) , style . zoom (24 ) ) 
self . image . set_f rompixbuf (scaled_buf ) 
self . image . show ( ) 

def extractimage (self , filename) : 

zf = zipfile . ZipFile ( filename, 'r') 

image^files = zf . namelist ( ) 

image_f iles . sort ( ) 

f ile_to_extract = image_f iles [ ] 

extract_new_f ilename = self .make_new_f ilename ( 

f ile_to_extract ) 
if extract_new_f ilename is None or \ 

extract_new_f ilename == ' ' : 

# skip over directory name if the images 

# are in a subdirectory. 

f ile_to_extract = image_f iles [ 1 ] 
extract_new_f ilename = self . make_new_f ilename ( 
f ile_to_extract ) 

if len (image_f iles ) > 0: 

if self . save_extracted_f ile ( zf , f ile_to_extract ) : 
fname = os .path . j oin (self . get_activity_root () , 
' instance ' , 
extract_new_f ilename) 
return fname 

def save_extracted_f ile (self , zipfile, filename): 

"Extract the file to a temp directory for viewing" 
try: 

filebytes = zipfile . read (filename) 
except zipfile . BadZipf ile, err: 

print 'Error opening the zip file: %s' % (err) 

return False 
except KeyError, err: 

self . alert (' Key Error', 'Zipfile key not found: ' 
+ str ( filename) ) 

return 
outfn = self .make_new_f ilename (filename) 
if (outfn == ' ' ) : 

return False 
fname = os .path . j oin (self . get_activity_root () , 

'instance', outfn) 
f = open (fname, 'w') 
try: 

f. write (filebytes) 
finally: 

f . close ( ) 
return True 

def make_new_f ilename (self , filename) : 

partition_tuple = f ilename . rpartition ('/' ) 
return partition_tuple [ 2 ] 
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def create_preview_metadata (self , filename) : 

f ile_mimetype = mime . get_for_file ( filename) 
if not f ile_mimetype . startswith (' image/ ' ) : 
return ' ' 

scaled_pixbuf = \ 

gtk . gdk . pixbuf_new_f rom_f ile_at_size ( 

filename, 

style. zoom (320) , style. zoom (240) ) 
preview_data = [] 

def save_f unc (buf , data) : 
data . append (buf) 

scaled_pixbuf . save_to_callback (savefunc, 

'prig' , 

user_data=preview_data) 
preview_data = ' ' . j oin (preview^data) 

return preview data 

Let's look at this code one method at a time. 

Adding A Journal Entry 

We add a Journal entry when someone pushes a button on the gtk.FileChooser. This is 
the code that gets run: 

def create_j ournal_entry (self , widget, data=None): 
filename = self . _f ilechooser . get_f ilename ( ) 
j ournal_entry = datastore . create ( ) 
j ournal_entry. metadata [' title ' ] = \ 

self .make_new_f ilename ( 

filename) 
j ournal_entry. metadata [' title_set_by_user ' ] = '!' 
j ournal_entry. metadata [' keep ' ] = '0' 
f ile_mimetype = mime . get_for_file ( filename) 
if not f ile_mimetype is None: 

j ournal_entry . metadata [' mime_type ' ] = \ 
f ile_mimetype 
j ournal_entry .metadata [' buddies ' ] = ' ' 
if file_mimetype . startswith (' image/ ' ) : 

preview = self . create_preview_metadata (filename) 
elif f ile_mimetype == ' application/x-cbz ' : 

fname = self . extractimage ( filename) 

preview = self . create_preview_metadata (fname) 

os . remove ( fname) 
else : 

preview = ' ' 
if not preview == ' ' : 

j ournal_entry .metadata [' preview ' ] = \ 
dbus . ByteArray (preview) 
else : 

j ournal_entry .metadata [' preview ' ] = ' ' 
j ournal_entry . f ile_path = filename 
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datastore . write ( j ournal_entry) 

The only thing worth commenting on here is the metadata, title is what appears as #3 
in the picture below. title_set_by_user is set to 1 so that the Activity won't prompt the 
user to change the title when the Activity closes, keep refers to the little star that 
appears at the beginning of the Journal entry (see #1 in the picture below). Highlight it 
by setting this to 1, otherwise set to 0. buddies is a list of users that collaborated on 
the Journal entry, and in this case there aren't any (these show up as #4 in the picture 
below). 
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preview is an image file in the PNG format that is a screenshot of the Activity in 
action. This is created by the Activity itself when it is run so there is no need to make 
one when you add a Journal entry. You can simply use an empty string (") for this 
property. 

Because previews are much more visible in Sugar Commander than they are in the 
regular Journal Activity I decided that Sugar Commander should make a preview image 
for image files and comic books as soon as they are added to the Journal. To do this I 
made a pixbuf of the image that would fit within the scaled dimensions of 320x240 
pixels and made a dbus.ByteArray out of it, which is the format that the Journal uses 
to store preview images. 
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mime_type describes the format of the file and is generally assigned based on the 
filename suffix. For instance, files ending in .html have a MIME type of 'text/html'. 
Python has a package called mimetypes that takes a file name and figures out what its 
MIME type should be, but Sugar provides its own package to do the same thing. For 
most files either one would give the correct answer, but Sugar has its own MIME types 
for things like Activity bundles, etc. so for best results you really should use Sugar's 
mime package. You can import it like this: 

from sugar import mime 

The rest of the metadata (icon, modified time) is created automatically. 

NOT Adding A Journal Entry 

Sugar Activities by default create a Journal entry using the write_file() method. There 
will be Activities that don't need to do this. For instance, Get Internet Archive Books 
downloads e-books to the Journal, but has no need for a Journal entry of its own. The 
same thing is true of Sugar Commander. You might make a game that keeps track of 
high scores. You could keep those scores in a Journal entry, but that would require 
players to resume the game from the Journal rather than just starting it up from the 
Activity Ring. For that reason you might prefer to store the high scores in a file in the 
data directory rather than the Journal, and not leave a Journal entry behind at all. 

Sugar gives you a way to do that. First you need to specify an extra argument in your 
Activity's init () method like this: 

class SugarCommander (activity .Activity) : 

def init (self, handle, create_j ob j ect=True) : 

"The entry point to the Activity" 

activity .Activity . init (self, handle, False) 

Second, you need to override the close() method like this: 

def close (self, skip_save=False) : 

"Override the close method so we don't try to 

create a Journal entry." 

activity .Activity . close (self, True) 

That's all there is to it. 

Listing Out Journal Entries 

If you need to list out Journal entries you can use the findO method of datastore. The 
find method takes an argument containing search criteria. If you want to search for 
image files you can search by mime-type using a statement like this: 
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ds_objects, num_objects = datastore . f ind ( 
{ 'mime_type ' : [ ' image/ j peg ' , 
' image /gif ' , ' image/tiff ' , ' image /png ' ] } , 
properties=[ ' uid ' , 
'title', ' mime_type ' ] ) ) 

You can use any metadata attribute to search on. If you want to list out everything in 
the Journal you can use an empty search criteria like this: 

ds_objects, num_objects = datastore . find ({} , 
properties= [ 'uid' , 
'title', ' mime_type ' ] ) ) 

The properties argument specifies what metadata to return for each object in the list. 
You should limit these to what you plan to use, but always include uid. One thing you 
should never include in a list is preview. This is an image file showing what the 
Activity for the Journal object looked like when it was last used. If for some reason you 
need this there is a simple way to get it for an individual Journal object, but you never 
want to include it in a list because it will slow down your Activity enormously. 

Listing out what is in the Journal is complicated because of the datastore rewrite done 
for Sugar .84. Before .84 the datastore.findO method listed out both Journal entries and 
files on external media like thumb drives and SD cards and you need to figure out 
which is which. In .84 and later it only lists out Journal entries. Fortunately it is 
possible to write code that supports either behavior. Here is code in Sugar 
Commander that only lists Journal entries: 

def load_j ournal_table (self ) : 

self . btn_save .props . sensitive = False 

self . btn_delete .props . sensitive = False 

ds_mounts = datastore .mounts ( ) 

mountpoint_id = None 

if len (ds_mounts ) == 1 and ds_mounts[0] ['id'] == 1: 

pass 
else : 

for mountpoint in ds_mounts : 
id = mountpoint [' id' ] 
uri = mountpoint [' uri ' ] 
if uri . startswith (' /home ' ) : 
mountpoint_id = id 

query = { } 

if mountpoint_id is not None: 

query [ 'mountpoints ' ] = [ mountpoint^id ] 
ds_objects, num_objects = datastore . find ( 

query, properties= [ ' uid' , 

'title', ' mime_type ' ] ) 

self . ls_j ournal. clear () 

for i in xrange (0, num_objects, 1) : 

iter = self . ls_j ournal . append ( ) 

title = ds obj ects [ i] .metadata [' title ' ] 
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self . ls_j ournal.set (iter, 

COLUMN_TITLE, title) 
mime = ds_obj ects [ i] .metadata [' mime_type ' ] 
self . ls_journal . set (iter, COLUMN_MIME, mime) 
self . ls_journal.se t (iter, COLUMN_JOBJECT, 

ds_ob j ects [i] ) 
if not self . selected_j ournal_entry is None and \ 

self . selected_j ournal_entry . ob j ect_id == \ 
ds_objects [i] .object_id: 

self . select ion_j ournal . select_iter (iter) 

self. ls_ journal . set_sort_column_id (COLUMN_TITLE, 

gtk. SORT_ASCENDING) 
v_adjustment = \ 

self . list_scroller_j ournal . get_vadjustment ( ) 
v_adj ustment . value = 
return ds_ob j ects [ ] 

We need to use the datastore.mountsO method for two purposes: 

• In Sugar .82 and below it will list out all mount points, including the place the 
Journal is mounted on and the places external media is mounted on. The 
mountpoint is a Python dictionary that contains a uri property (which is the path 
to the mount point) and an id property (which is a name given to the mount 
point). Every Journal entry has a metadata attribute named mountpoint. The 
Journal uri will be the only one starting with /home, so if we limit the search to 
Journal objects where the id of that mountpoint equals the mountpoint metadata 
in the Journal objects we can easily list only objects from the Journal. 

• In Sugar .84 and later the datastore.mountsO method still exists but doesn't tell you 
anything about mountpoints. However, you can use the code above to see if there 
is only one mountpoint and if its id is 1 . If it is you know you're dealing with the 
rewritten datastore of .84 and later. The other difference is that the Journal objects 
no longer have metadata with a key of mountpoint. If you use the code above it 
will account for this difference and work with either version of Sugar. 

What if you want the Sugar .82 behavior, listing both Journal entries and USB files as 
Journal objects, in both .82 and .84 and up? I wanted to do that for View Slides and 
ended up using this code: 

def load_j ournal_table (self ) : 

ds_objects, num_objects = datastore . find ( 

{ 'mime_type ' : [ ' image/ j peg ' , 

'image/gif', 'image/tiff', 'iraage/png' ] } , 

properties= [ ' uid' , 'title', ' mime_type ' ] ) 
self . ls_right . clear ( ) 
for i in xrange (0, num_objects, 1) : 

iter = self . ls_right . append ( ) 

title = ds_obj ects [i] .metadata [' title ' ] 

mime_type = ds_obj ects [ i] .metadata [' mime_type ' ] 

if mime_type == ' image/ jpeg' \ 
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and not title . endswith ('. jpg ' ) \ 

and not title . endswith ('. jpeg ' ) \ 

and not title . endswith ('. JPG ' ) \ 

and not title . endswith ('. JPEG 1 ) : 

title = title + '.jpg' 
if mime_type == 'image/png' \ 

and not title . endswith ('. png ' ) \ 

and not title . endswith ('. PNG ') : 

title = title + '.png' 
if mime_type == 'image/gif' \ 

and not title . endswith ('. gif ') \ 

and not title. endswith('. GIF'): 

title = title + '.gif 
if mime_type == 'image/tiff' \ 

and not title . endswith ('. tiff ') \ 

and not title . endswith ('. TIFF ') : 

title = title + ' .tiff 
self . ls_right. set (iter, COLUMN_IMAGE, title) 
j ob j ect_wrapper = Job j ectWrapper ( ) 
j ob j ect_wrapper . set_j ob j ect (ds_ob j ects [ i ] ) 
self . ls_right . set (iter, COLUMN_PATH, 

j ob j ect_wrapper ) 

valid_endings = ('.jpg', '.jpeg', '.JPEG', 

'.JPG', '.gif, '.GIF', '.tiff, 

' .TIFF' , ' .png' , ' .PNG' ) 
ds_mounts = datastore .mounts ( ) 
if len (ds_mounts ) == 1 and ds_mounts [ ] ['id'] == 1: 

# datastore .mounts ( ) is stubbed out, 

# we're running .84 or better 

for dirname, dirnames, filenames in os.walk( 
' /media ' ) : 
if '. olpc . store ' in dirnames: 

dirnames . remove ('.olpc. store') 
# don't visit .olpc. store directories 
for filename in filenames : 

if filename . endswith (valid_endings) : 
iter = self . ls_right . append ( ) 
j ob j ect_wrapper = Job j ectWrapper ( ) 
j ob j ect_wrapper . set_f ile_path ( 

os .path . j oin (dirname, filename)) 
self .ls_right . set (iter, COLUMN_IMAGE, 

filename) 
self . ls_right. set (iter, COLUMN_PATH, 
j ob j ect_wrapper ) 

self . ls_right . set_sort_column_id (COLUMN_IMAGE, 
gtk. SORT_ASCENDING) 

In this case I use the datastore.mountsO method to figure out what version of the 
datastore I have and then if I'm running .84 and later I use os.walkO to create a flat list of 
all files in all directories found under the directory /media (which is where USB and SD 
cards are always mounted). I can't make these files into directories, but what I can do is 
make a wrapper class that can contain either a Journal object or a file and use those 
objects where I would normally use Journal objects. The wrapper class looks like this: 
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class JobjectWrapper ( ) : 

def init (self): 

self. jobject = None 

self. file_path = None 

def set_j obj ect ( self , jobject): 
self. jobject = jobject 

def set_f ile_path ( self , file_path) : 
self. file_path = file_path 

def get_f ile_path ( self ) : 

if self. jobject != None: 

return self . j ob j ect . get_f ile_path ( ) 

else : 

return self. file_path 



Using Journal Entries 



When you're ready to read a file stored in a Journal object you can use the 
get_file_path() method of the Journal object to get a file path and open it for reading, like 
this: 

fname = j ob j ect . get_f ile_path ( ) 

One word of caution: be aware that this path does not exist until you call get_file_pa th () 
and will not exist long after. With the Journal you work with copies of files in the 
Journal, not the originals. For that reason you don't want to store the return value of 
get_file_path() for later use because later it may not be valid. Instead, store the Journal 
object itself and call the method right before you need the path. 

Metadata entries for Journal objects generally contain strings and work the way you 
would expect, with one exception, which is the preview. 

def create_preview ( self , object_id): 
jobject = datastore . get (ob j ect_id) 

if j obj ect .metadata . has_key (' preview ' ) : 
preview = j obj ect .metadata [' preview ' ] 
if preview is None or preview == ' ' or 
preview == 'None' : 
if jobject. metadata!' mime_type ' ] . startswith ( 

' image/ ' ) : 

filename = j ob j ect . get_f ile_path ( ) 

self . show_image ( filename) 

return 
if jobject .metadata [ 'mime_type ' ] == \ 

' application/x-cbz ' : 

filename = j ob j ect . get_f ile_path ( ) 

fname = self . extractimage (filename) 

self . show_image ( fname) 

os . remove ( fname) 

return 
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if j obj ect .metadata . has_key (' preview ' ) and \ 
len (j obj ect .metadata [' preview '] ) > 4: 

if jobject .metadata [ 'preview' ][ 1 : 4 ] == 'PNG': 
preview_data = j obj ect . metadata [' preview ' ] 

else : 

import base64 

preview_data = base64 . b64decode ( 
j obj ect .metadata [ 'preview ' ] ) 

loader = gtk . gdk . Pixbuf Loader ( ) 
loader. write (preview_data) 
scaled_buf = loader . get_pixbuf ( ) 
loader . close ( ) 

self . image . set_f rompixbuf (scaled_buf ) 
self . image . show ( ) 
else : 

self . image . clear ( ) 
self . image . show ( ) 

The preview metadata attribute is different in two ways: 

• We should never request preview as metadata to be returned in our list of Journal 
objects. We'll need to get a complete copy of the Journal object to get it. Since we 
already have a Journal object we can get the complete Journal object by getting its 
object id then requesting a new copy from the datastore using the id. 

• The preview image is a binary object (dbus.ByteArray) but in versions of Sugar 
older than .82 it will be stored as a text string. To accomplish this it is base 64 
encoded. 

The code you would use to get a complete copy of a Journal object looks like this: 

object_id = j ob j ect . ob j ect_id 
jobject = datastore . get (obj ect_id) 

Now for an explanation of base 64 encoding. You've probably heard that computers 
use the base two numbering system, in which the only digits used are 1 and 0. A unit 
of data storage that can hold either a zero or a one is called a bit. Computers need to 
store information besides numbers, so to accomodate this we group bits into groups of 8 
(usually) and these groups are called bytes. If you only use 7 of the 8 bits in a byte you 
can store a letter of the Roman alphabet, a punctuation mark, or a single digit, plus 
things like tabs and line feed characters. Any file that can be created using only 7 bits 
out of the 8 is called a text file. Everything that needs all 8 bits of each byte to make, 
including computer programs, movies, music, and pictures of Jessica Alba is a binary. 
In versions of Sugar before .82 Journal object metadata can only store text strings. 
Somehow we need to represent 8-bit bytes in 7 bits. We do this by grouping the bytes 
together into a larger collection of bits and then splitting them back out into groups of 7 
bits. Python has the base64 package to do this for us. 
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Base 64 encoding is actually a pretty common technique. If you've ever sent an email 
with an attached file the file was base 64 encoded. 

The code above has a couple of ways of creating a preview image. If the preview 
metadata contains a PNG image it is loaded into a pixbuf and displayed. If there is no 
preview metadata but the MIME type is for an image file or a comic book zip file we 
create the preview from the Journal entry itself. 

The code checks the first three characters of the preview metadata to see if they are 
'PNG'. If so, the file is a Portable Network Graphics image stored as a binary and 
does not need to be converted from base 64 encoding, otherwise it does. 

Updating A Journal Object 

The code to update a Journal object looks like this: 

def update_entry ( self ) : 
needs_update = False 

if self . selected_j ournal_entry is None: 
return 

object_id = self . selected_j ournal_entry . obj ect_id 
jobject = datastore . get (ob j ect_id) 

old_title = j obj ect .metadata . get (' title ' , None) 
if old_title != self . title_entry .props . text : 

j obj ect .metadata [' title ' ] = \ 

self . title_entry .props .text 

jobject .metadata [' title_set_by_user ' ] = '1' 

needs_update = True 

old_tags = j obj ect .metadata . get (' tags ' , None) 
new_tags = \ 

self . tags_textview .props .buffer .props . text 
if old_tags != newtags: 

j obj ect .metadata [' tags ' ] = new_tags 

needs_update = True 

old_description = \ 

jobject. metadata. get ( 'description' , None) 
new_description = \ 

self . description_textview .props. buffer. props. text 
if old_description != new_description : 

j obj ect .metadata [' description ' ] = \ 
new_de script ion 

needs_update = True 

if needs_update : 

datastore. write (j obj ect, update_mtime=False, 
reply_handler=self . datastore_write_cb, 
error handler=self . datastore write error cb) 
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self . btn_save .props . sensitive = False 

def datastore_write_cb (self ) : 
pass 

def datastore_write_error_cb (self , error) : 
logging. error ( 

' sugarcommander . datastore_write_error_cb : ' 
>r ' % error) 
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Deleting A Journal Entry 

The code to delete a Journal entry is this: 

def delete_button_press_event_cb (self , entry, event): 
datastore . delete ( 

self . select ed_j ournal_entry . ob j ect_id) 

Getting Callbacks From The Journal Using D-Bus 

In the chapter on Making Shared Activities we saw how D-Bus calls sent over 
Telepathy Tubes could be used to send messages from an Activity running on one 
computer to the same Activity running on a different computer. D-Bus is not normally 
used that way; typically it is used to send messages between programs running on the 
same computer. 

For example, if you're working with the Journal you can get callbacks whenever the 
Journal is updated. You get the callbacks whether the update was done by your 
Activity or elsewhere. If it is important for your Activity to know when the Journal has 
been updated you'll want to get these callbacks. 

The first thing you need to do is define some constants and import the dbus package: 

DS_DBUS_SERVICE = ' org . laptop . sugar . DataStore ' 
DS_DBUS_INTERFACE = ' org . laptop . sugar . DataStore ' 
DS_DBUS_PATH = ' /org/laptop/sugar /DataStore ' 
import dbus 

Next, in your init () method put code to connect to the signals and do the callbacks: 

bus = dbus . SessionBus ( ) 
remote_ob j ect = bus . get_ob j ect ( 

DS_DBUS_SERVICE, DS_DBUS_PATH) 
_datastore = dbus . Interface (remote_obj ect , 

DS_DBUS_INTERFACE) 
_data store . connect_to_signal (' Created ' , 

self . _datastore_created_cb) 
_data store . connect_to_signal ( 'Updated ' , 

self . _datastore_updated_cb) 
_data store . connect_to_signal (' Deleted ' , 
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self ._datastore_deleted_cb) 

The methods being run by the callbacks might look something like this: 

def datastore_created_cb (self , uid) : 
new_jobject = datastore . get (uid) 
iter = self . ls_j ournal . append ( ) 
title = new_j obj ect .metadata [' title ' ] 
self . ls_j ournal. set (iter, 

COLUMN_TITLE, title) 
mime = new_j obj ect .metadata [' mime_type ' ] 
self . ls_j ournal. set (iter, 

COLUMN_MIME, mime) 
self . ls_j ournal. set (iter, 

COLUMN_JOBJECT, new_jobject) 

def datastore_updated_cb (self , uid): 
new_jobject = datastore . get (uid) 
iter = self . ls_j ournal . get_iter_f irst ( ) 
for row in self. Is journal: 

j Obj ect = row[COLUMN_JOBJECT] 
if j ob j ect . ob j ect_id == uid: 

title = new_j obj ect .metadata [' title ' ] 
self . ls_j ournal . set_value (iter, 

COLUMN_TITLE, title) 
break 
iter = self . ls_j ournal . iter_next (iter ) 
object_id = \ 

self . selected_j ournal_entry . obj ect_id 
if object_id == uid: 

self . set_f orm_f ields (new_j obj ect ) 

def datastore_deleted_cb (self , uid): 
save_path = self . selected_path 
iter = self . ls_j ournal . get_iter_f irst ( ) 
for row in self. Is journal: 

j Obj ect = row[COLUMN_JOBJECT] 
if j ob j ect . ob j ect_id == uid: 

self. ls_j ournal. remove (iter) 
break 
iter = self . ls_j ournal . iter_next (iter ) 

try : 

self . select ion_j ournal . select_path ( 

save_path) 
self . tv_j ournal . grab_focus () 
except : 

self . title_entry . set_text ( ' ' ) 
description_textbuf f er = \ 

self . description_textview . get_buf f er ( ) 
description_textbuf f er . set_text ( ' ' ) 
tags_textbuf f er = \ 

self . tags_textview . get_buf f er ( ) 
tags_textbuf f er . set_text ( ' ' ) 
self . btn_save . props . sensitive = False 
self . btn_delete .props . sensitive = False 
self . image . clear ( ) 
self . image . show ( ) 
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The uid passed to each callback method is the object id of the Journal object that has 
been added, updated, or deleted. If an entry is added to the Journal I get the Journal 
object from the datastore by its uid, then add it to the gtk.ListStore for the 
gtk.TreeModel I'm using to list out Journal entries. If an entry is updated or deleted I 
need to account for the possibility that the Journal entry I am viewing or editing may 
have been updated or removed. I use the uid to figure out which row in the 
gtkListStore needs to be removed or modified by looping through the entries in the 
gtkListStore looking for a match. 

Now you know everything you'll ever need to know to work with the Journal. 
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X O • Making Activities Using PyG 



ame 



Introduction 

PyGame and PyGTK are two different ways to make a Python program with a 
graphical user interface. Normally you would not use both in the same program. Each 
of them has its own way of creating a window and each has its own way of handling 
events. 

The base class Activity we have been using is an extension of the PyGTK Window class 
and uses PyGTK event handling. The toolbars all Activities use are PyGTK 
components. In short, any Activity written in Python must use PyGTK. Putting a 
PyGame program in the middle of a PyGTK program is a bit like putting a model ship 
in a bottle. Fortunately there is some Python code called SugarGame that will make it 
possible to do that. 

Before we figure out how we'll get it in the bottle, let's have a look at our ship. 

Making A Standalone Game Using PyGame 

As you might expect, it's a good idea to make a standalone Python game using PyGame 
before you make an Activity out of it. I am not an experienced PyGame developer, but 
using the tutorial Rapid Game Development with Python by Richard Jones at this URL: 

http://richard.cgpublisher.com/product/pub.84/prod.ll 

I was able to put together a modest game in about a day. It would have been sooner 
but the tutorial examples had bugs in them and I had to spend a fair amount of time 
using The GIMP to create image files for the sprites in the game. 

Sprites are small images, often animated, that represent objects in a game. They 
generally have a transparent background so they can be drawn on top of a background 
image. I used the PNG format for my sprite files because it supports having an alpha 
channel (another term that indicates that part of the image is transparent). 

PyGame has code to display background images, to create sprites and move them 
around on the background, and to detect when sprites collide with one another and do 
something when that happens. This is the basis for making a lot of 2D games. There 
are lots of games written with PyGame that could be easily adapted to be Sugar 
Activities. 
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My game is similar to the car game in the tutorial, but instead of a car I have an 
airplane. The airplane is the Demoiselle created by Alberto Santos-Dumont in 1909. 
Instead of having "pads" to collide with I have four students of Otto Lilienthal hovering 
motionless in their hang gliders. The hang gliders pitch downwards when Santos- 
Dumont collides with them. The controls used for the game have been modified too. I 
use the Plus and Minus keys on both the main keyboard and the keypad, plus the 
keypad 9 and 3 keys, to open and close the throttle and the Up and Down arrows on 
both the main keyboard and the keypad to move the joystick forward and back. Using 
the keypad keys is useful for a couple of reasons. First, some versions of sugar- 
emulator don't recognize the arrow keys on the main keyboard. Second, the arrow 
keys on the keypad map to the game controller on the XO laptop, and the non-arrow 
keys on the keypad map to the other buttons on the XO laptop screen. These buttons 
can be used to play the game when the XO is in tablet mode. 

As a flight simulator it isn't much, but it does demonstrate at least some of the things 
PyGame can do. Here is the code for the game, which I'm calling Demoiselle: 

# ! /usr/bin/env python 
import pygame 
import math 
import sys 

class Demoiselle: 

"This is a simple demonstration of using PyGame \ 
sprites and collision detection." 
def init (self) : 

self . background = pygame . image . load (' sky . jpg ' ) 

self. screen = pygame . display . get_surf ace ( ) 

self . screen .blit (self .background, (0, 0)) 

self. clock = pygame . time . Clock ( ) 

self. running = True 

gliders = [ 

GliderSprite ( (200, 200)), 

GliderSprite ( (800, 200)), 

GliderSprite ( (200, 600)), 

GliderSprite ( (800, 600)), 
] 
self. glider_group = pygame . sprite . RenderPlain ( 

gliders) 

def run ( self) : 

"This method processes PyGame messages" 

rect = self . screen . get_rect ( ) 

airplane = AirplaneSprite (' demoiselle .png ' , 

rect . center) 
airplane_sprite = pygame . sprite . RenderPlain ( 

airplane) 

while self . running : 

self. clock. tick (30 ) 
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for event in pygame . event . get ( ) : 
if event. type == pygame . QUIT : 
self. running = False 
return 
elif event. type == pygame . VTDEORESIZE : 
pygame .display . set_mode (event . size, 

pygame .RESIZABLE) 
self. screen. blit (self. background, 
(0,0)) 

if not hasattr (event , 'key') : 

continue 
down = event. type == pygame . KEYDOWN 
if event. key == pygame . K_DOWN or \ 

event. key == pygame . K_KP2 : 

airplane . j oystick_back = down * 5 
elif event. key == pygame. K_UP or \ 

event. key == pygame . K_KP8 : 

airplane . j oystick_f orward = down * -5 
elif event. key == pygame . K_EQUALS or \ 

event. key == pygame . K_KP_PLUS or \ 

event. key == pygame . K_KP9 : 

airplane . throttle_up = down * 2 
elif event. key == pygame . K_MINUS or \ 

event. key == pygame . K_KP_MINUS or \ 



event. key == pygame . K_KP3 : 
airplane . throttle_down = c 



down * -2 

self . glider_group .clear (self. screen, 

self. background) 
airplane_sprite .clear (self. screen, 

self. background) 
collisions = pygame . sprite . spritecollide ( 

airplane, 

self . glider_group, False) 
self . glider_group . update (collisions) 
self . glider_group .draw (self. screen) 
airplane_sprite . update () 
airplane_sprite .draw (self. screen) 
pygame .display. flip () 

class AirplaneSprite (pygame . sprite . Sprite) : 

"This class represents an airplane, the Demoiselle \ 

created by Alberto Santos-Dumont" 

MAX_FORWARD_SPEED =10 

MIN_FORWARD_SPEED = 1 

ACCELERATION = 2 

TURN_SPEED = 5 

def init (self, image, position) : 

pygame .sprite. Sprite . init (self) 

self . src_image = pygame . image . load (image) 

self.rect = pygame. Rect ( 

self . src_image . get_rect ( ) ) 

self . position = position 

self . rect . center = self .position 

self . speed = 1 

self . direction = 
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self . j oystick_back = self . j oystick_f orward = \ 
self . throttle_down = self . throttle_up = 

def update (self) : 

"This method redraws the airplane in response\ 

to events . " 

self. speed += (self . throttle_up + 

self . throttle_down) 
if self. speed > self .MAX_FORWARD_SPEED : 

self. speed = self .MAX_FORWARD_SPEED 
if self. speed < self .MIN_FORWARD_SPEED : 

self. speed = self .MIN_FORWARD_SPEED 
self . direction += (self . j oystick_f orward + \ 

self . j oystick_back) 
x_coord, y_coord = self .position 
rad = self . direction * math. pi / 180 
x_coord += -self. speed * math . cos (rad) 
y_coord += -self. speed * math . sin (rad) 
screen = pygame . display . get_surf ace ( ) 
if y_coord < : 

y_coord = screen . get_height ( ) 

if x_coord < : 

x_coord = screen . get_width ( ) 

if x_coord > screen . get_width ( ) : 
x_coord = 

if y_coord > screen . get_height ( ) : 

y_coord = 
self . position = (x_coord, y_coord) 
self. image = pygame . transform. rotate ( 

self . srcimage, -self . direction) 
self.rect = self . image . get_rect ( ) 
self . rect . center = self .position 

class GliderSprite (pygame . sprite . Sprite) : 

"This class represents an individual hang \ 
glider as developed by Otto Lilienthal." 

def init (self, position) : 

pygame .sprite. Sprite . init (self) 

self. normal = pygame . image . load ( 

' glider_normal . png ' ) 
self.rect = pygame . Rect (self . normal . get_rect () ) 
self . rect . center = position 
self. image = self. normal 

self. hit = pygame . image . load (' glider_hit . png ' ) 
def update (self, hit_list) : 

"This method redraws the glider when it collides\ 
with the airplane and when it is no longer \ 
colliding with the airplane." 
if self in hit list: 

self. image = self. hit 
else : 

self. image = self. normal 

def main ( ) : 

"This function is called when the game is run \ 
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from the command line" 

pygame . init ( ) 

pygame .display. set mode ( ( , 

game = Demoiselle () 

game . run ( ) 

sys . exit ( ) 



pygame .RESIZABLE) 



if 



main ( ) 
And here is the game in action: 




You'll find the code for this game in the file demoiselle.py in the book examples project 
in Git. 

Introducing Sugar Game 

SugarGame is not part of Sugar proper. If you want to use it you'll need to include the 
Python code for SugarGame inside your Activity bundle. I've included the version of 
SugarGame I'm using in the book examples project in the sugargame directory, but 
when you make your own games you'll want to be sure and get the latest code to 
include. You can do that by downloading the project from Gitorious using these 
commands: 



mkdir sugargame 

cd sugargame 

git clone git : //git . sugarlabs . org/sugargame/mainline . git 
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You'll see two subdirectories in this project: sugargame and test, plus a README.txt 
file that contains information on using sugargame in your own Activities. The test 
directory contains a simple PyGame program that can be run either standalone or as an 
Activity. The standalone program is in the file named TestGame.py. The Activity, 
which is a sort of wrapper around the standalone version, is in file TestActivity.py. 

If you run TestGame.py from the command line you'll see it displays a bouncing ball 
on a white background. To try running the Activity version you'll need to run 

. /setup . py dev 

from the command line first. I was not able to get the Activity to work under sugar- 
emulator until I made two changes to it: 

• I made a copy of the sugargame directory within the test directory. 

• I removed the line reading "sys.path.append('..') # Import sugargame package 
from top directory." from TestActivity.py. Obviously this line is supposed to 
help the program find the sugargame directory in the project but it didn't work in 
Fedora 10. Your own experience may be different. 

The Activity looks like this: 





The PyGame toolbar has a single button that lets you make the bouncing ball pause 
and resume bouncing. 
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Making A Sugar Activity Out Of A PyGame Program 

Now it's time to put our ship in that bottle. The first thing we need to do is make a 
copy of the sugargame directory of the SugarGame project into the mainline directory 
of our own project. 

The README.txt file in the SugarGame project is worth reading. It tells us to make an 
Activity based on the TestActivity.py example in the SugarGame project. This will be 
our bottle. Here is the code for mine, which is named DemoiselleActivity.py: 

# DemoiselleActivity . py 

from gettext import gettext as 

import gtk 

import pygame 

from sugar . activity import activity 

from sugar . graphics . toolbutton import ToolButton 

import gobject 

import sugargame . canvas 

import demoiselle2 

class DemoiselleActivity (activity .Activity) : 

def init (self, handle) : 

super (DemoiselleActivity, self) . init (handle) 

# Build the activity toolbar. 
self . build_toolbar ( ) 

# Create the game instance. 

self. game = demoiselle2 . Demoiselle ( ) 

# Build the Pygame canvas. 
self ._pygamecanvas = \ 

sugargame .canvas . Pygame Canvas (self) 

# Note that set_canvas implicitly calls 

# read_file when resuming from the Journal. 
self . set_canvas (self . _py game canvas) 

self . score = ' ' 

# Start the game running. 

self . _pygame canvas . run_pygame (self . game .run) 

def build_toolbar ( self ) : 

toolbox = activity . ActivityToolbox (self ) 
activity_toolbar = toolbox . get_activity_toolbar ( ) 
activity_toolbar . keep .props . visible = False 
activity_toolbar . share .props . visible = False 

self . view_toolbar = ViewToolbar ( ) 

toolbox . add_toolbar (_ ( ' View ' ) , self. view_toolbar ) 

self . view_toolbar .connect ( 'go-fullscreen' , 

self . view_toolbar_go_f ullscreen_cb) 
self. view toolbar . show ( ) 
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toolbox . show ( ) 

self . set_toolbox (toolbox) 

def view_toolbar_go_f ullscreen_cb (self , view_toolbar ) : 
self. fullscreen () 

def read_f ile ( self , file_path) : 

score_file = open ( f ile_path, "r") 
while score_file: 

self. score = score_f ile . readline ( ) 

self . game . set_score (int (self. score)) 
score_f ile .close ( ) 

def write_f ile (self , file_path) : 
score = self . game . getscore ( ) 
f = open ( f ile_path, ' wb ' ) 
try : 

f. write (str (score) ) 
finally: 

f . close 

class ViewToolbar (gtk . Toolbar ) : 

gtype_name = 'ViewToolbar' 

gsignals = { 

'needs-update-size ' : (gob j ect . SIGNAL_RUN_FIRST, 

gobject . TYPE_NONE, 
([])), 
'go-fullscreen' : (gob j ect . SIGNAL_RUN_FIRST, 
gobject .TYPE_NONE, 
([])) 
} 

def init (self) : 

gtk. Toolbar . init (self) 

self . fullscreen = ToolButton (' view-fullscreen ' ) 
self. fullscreen. set_tooltip (_(' Fullscreen')) 
self. fullscreen. connect ( 'clicked' , 

self . f ullscreen_cb) 
self . insert (self . fullscreen, -1) 
self. fullscreen. show () 

def f ullscreen_cb (self , button): 
self . emit ( 'go-fullscreen' ) 

This is a bit fancier than TestActivity.py. I decided that my game didn't really need to 
be paused and resumed, so I replaced the PyGame toolbar with a View toolbar that 
lets the user hide the toolbar when it is not needed. I use the read_file() and write_file() 
methods to save and restore the game score. (Actually this is faked, because I never put 
in any scoring logic in the game). I also hide the Keep and Share controls in the main 
toolbar. 

As you would expect, getting a ship in a bottle does require the ship to be modified. 
Here is demoiselle2.py, which has the modifications: 
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# ! /usr/bin/env python 
import pygame 
import gtk 
import math 
import sys 

class Demoiselle: 

"This is a simple demonstration of using PyGame \ 
sprites and collision detection." 
def init (self): 

self. clock = pygame . time . Clock ( ) 

self. running = True 

self . background = pygame . image . load (' sky . jpg ' ) 

def get_score ( self ) : 
return ' 99 ' 

def run ( self) : 

"This method processes PyGame messages" 

screen = pygame . display . get_surf ace ( ) 
screen . blit ( self . background, (0, 0)) 

gliders = [ 

GliderSprite ( (200, 200)), 

GliderSprite ( (800, 200)), 

GliderSprite ( (200, 600)), 

GliderSprite ( (800, 600)), 
] 
glider_group = pygame . sprite . RenderPlain (gliders ) 

rect = screen . get_rect ( ) 

airplane = AirplaneSprite (' demoiselle .png ' , 

rect . center) 
airplane_sprite = pygame . sprite . RenderPlain ( 

airplane) 

while self . running : 

self. clock. tick (30 ) 

# Pump GTK messages, 
while gtk . eventspending ( ) : 

gtk . main_iteration ( ) 

# Pump PyGame messages. 

for event in pygame . event . get ( ) : 
if event. type == pygame. QUIT: 
self. running = False 
return 
elif event. type == pygame . VTDEORESIZE : 
pygame .display . setmode (event . size, 

pygame .RESIZABLE) 
screen .blit (self .background, (0, 0)) 

if not hasattr (event , 'key') : 

continue 
down = event. type == pygame . KEYDOWN 
if event. key == pygame. K DOWN or \ 
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event . key == pygame . K_KP2 : 
airplane . j oystick_back = down * 5 

elif event . key == pygame . K_UP or \ 
event . key == pygame . K_KP 8 : 
airplane . j oystick_f orward = down * -5 

elif event . key == pygame . K_EQUALS or \ 
event . key == pygame . K_KP_PLUS or \ 
event . key == pygame . K_KP9 : 
airplane . throttle_up = down * 2 

elif event . key == pygame . K_MINUS or \ 

event. key == pygame . K_KP_MINUS or \ 
event . key == pygame . K_KP3 : 
airplane . throttle_down = down * -2 

glider_group .clear (screen, self. background) 
airplane_sprite. clear (screen, self. background) 
collisions = pygame . sprite . spritecollide ( 

airplane, 

glider_group, False) 
glider_group . update (collisions) 
glider_group .draw (screen) 
airplane_sprite .update ( ) 
airplane_sprite. draw (screen) 
pygame .display . flip ( ) 

class AirplaneSprite (pygame . sprite . Sprite) : 

"This class represents an airplane, the Demoiselle \ 

created by Alberto Santos-Dumont" 

MAX_FORWARD_SPEED =10 

MIN_FORWARD_SPEED = 1 

ACCELERATION = 2 

TURN_SPEED = 5 

def init (self, image, position) : 

pygame .sprite. Sprite . init (self) 

self . src_image = pygame . image . load (image) 

self.rect = pygame . Rect (self . src_image . get_rect () ) 

self . position = position 

self . rect . center = self .position 

self . speed = 1 

self . direction = 

self . j oystick_back = self . j oystick_f orward = \ 
self . throttle_down = self . throttle_up = 

def update (self) : 

"This method redraws the airplane in response\ 

to events . " 

self. speed += (self . throttle_up + 

self . throttle_down) 
if self. speed > self .MAX_FORWARD_SPEED : 

self. speed = self .MAX_FORWARD_SPEED 
if self. speed < self .MIN_FORWARD_SPEED : 

self. speed = self .MIN_FORWARD_SPEED 
self . direction += (self . j oystick_f orward + 

self . j oystick_back) 
x_coord, y_coord = self .position 
rad = self . direction * math. pi / 180 
x_coord += -self. speed * math . cos (rad) 
y_coord += -self. speed * math . sin (rad) 
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screen = pygame . display . get_surf ace ( ) 
if y_coord < : 

y_coord = screen . get_height ( ) 

if x_coord < : 

x_coord = screen . get_width ( ) 

if x_coord > screen . get_width ( ) : 
x_coord = 

if y_coord > screen . get_height ( ) : 

y_coord = 
self . position = (x_coord, y_coord) 
self. image = pygame . transform. rotate ( 

self . src_image, -self . direction) 
self.rect = self . image . get_rect ( ) 
self . rect . center = self .position 

class GliderSprite (pygame . sprite . Sprite) : 

"This class represents an individual hang \ 
glider as developed by Otto Lilienthal." 

def init (self, position) : 

pygame .sprite. Sprite . init (self) 

self. normal = pygame . image . load ( 

' glider_normal . png ' ) 
self.rect = pygame . Rect (self . normal . get_rect () ) 
self . rect . center = position 
self. image = self. normal 

self. hit = pygame . image . load (' glider_hit .png ' ) 
def update (self, hit_list) : 

"This method redraws the glider when it collides\ 
with the airplane and when it is no longer \ 
colliding with the airplane." 
if self in hit_list: 

self. image = self. hit 
else : 

self. image = self. normal 

def main ( ) : 

"This function is called when the game is run \ 

from the command line" 

pygame . init ( ) 

pygame . display . set mode (( , 0), pygame . RESIZABLE) 

game = Demoiselle () 

game . run ( ) 

sys . exit ( ) 

if name == ' main ': 

main ( ) 

Why not load both demoiselle.py and demoiselle2.py in Eric and take a few minutes 
to see if you can figure out what changed between the two versions? 

Surprisingly little is different. I added some code to the PyGame main loop to check for 
PyGTK events and deal with them: 

while self . running : 
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self. clock. tick (30 ) 

# Pump GTK messages . 
while gtk . events_pending ( ) : 

gtk . main_iteration ( ) 

# Pump PyGame messages. 

for event in pygame . event . get ( ) : 
if event. type == pygame. QUIT: 
self. running = False 
return 
elif event. type == pygame . VIDEORESIZE : 
pygame .display . set_mode (event . size, 

pygame .RESIZABLE) 
screen .blit (self . background, (0, 0)) 

if not hasattr (event , 'key') : 

continue 
down = event. type == pygame . KEYDOWN 
if event . key == pygame . K_DOWN or \ 

. . . continue dealing with PyGame events . . . 

This has the effect of making PyGame and PyGTK take turns handling events. If this 
code was not present GTK events would be ignored and you'd have no way to close the 
Activity hide the toolbar, etc. You need to add import gtk at the top of the file so these 
methods can be found. 

Of course I also added the methods to set and return scores: 

def get_score (self ) : 
return self. score 

def set_score (self , score) : 
self. score = score 

The biggest change is in the init () method of the Demoiselle class. Originally I 

had code to display the background image on the screen: 

def init (self) : 

self . background = pygame . image . load (' sky . jpg ' ) 
self. screen = pygame . display . get_surf ace ( ) 
self . screen .blit (self .background, (0, 0)) 

The problem with this is that sugargame is going to create a special PyGTK Canvas 
object to replace the PyGame display and the DemoiselleActivity code hasn't done that 
yet, so self.screen will have a value of None. The only way to get around that is to 

move any code that refers to the display out of the init () method of the class and 

into the beginning of the method that contains the event loop. This may leave you with 

an init () method that does little or nothing. About the only thing you'll want there 

is code to create instance variables. 
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Nothing we have done to demoiselle2.py will prevent it from being run as a 
standalone Python program. 

To try out the game run ./setup.py dev from within the 

Making_Activities_Using_PyGame directory. When you try out the Activity it 
should look like this: 
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-L y • Making New Style Toolbars 



Introduction 

They say "There's no Toolbar like an old Toolbar" and if your users are not running the 
very latest version of Sugar they're right. Activities will need to support the original 
style toolbars for some time to come. However, it is possible to make an Activity that 
supports both and that is what we'll do in this chapter. 

The new style toolbars came about because of problems with the old toolbars. Activity 
users were having a hard time figuring out how to quit an Activity because the Close 
button is only on the Activity toolbar. If the Activity starts on a different toolbar, as 
many do, it is not obvious that you need to switch to the Activity toolbar to quit the 
Activity. Another issue brought up was that the Tabs for the toolbars took up screen 
real estate that could be better used elsewhere. Let's compare toolbars for similar 
Activities. First, the old style toolbar for Read Etexts: 



OO 



• u 



Read b View 



Now compare it with the new style toolbar for the Read Activity: 



X^OO 



This is thinner than the older version and the Close button is always visible. Some 
functions are on the main toolbar and others are attached to toolbars that drop down 
when you click on their icon. First, the new Activity drop down toolbar: 




[ ed Planpt. by Charles Louis Fontenay 



Next the Edit toolbar: 
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Finally, the View toolbar: 






* * * 



Adding New Style Toolbars to Read Etexts II 

When working on the original Read Etexts Activity I borrowed a lot of user interface 
code from the original Read Activity and I see no reason to stop doing that now. One 
complication to doing this is that Read has some dependencies that prevent the latest 
version of Read from working with older versions of Sugar, and that being the case 
there is no need at all for Read to support both old and new toolbars. Read Etexts IV 
will not be so fortunate; it will need to figure out at runtime what kind of toolbar is 
supported and use that. 

I am able to test the Activity with both old and new style toolbars on the same box 
because I'm running Fedora 11, which has an installed Sugar environment that supports 
the old toolbars, plus I have downloaded and run sugar-jhbuild, which supports the 
new toolbars in its version of Sugar. 

Here is the code for ReadEtextsActivity4.py: 

import os 

import re 

import logging 

import time 

import zipfile 

import gtk 

import pango 

import dbus 

import gobject 

import telepathy 

from sugar . activity import activity 

from sugar . graphics . toolbutton import ToolButton 

_NEW_TOOLBAR_SUPPORT = True 
try : 

from sugar . graphics . toolbarbox import ToolbarBox 

from sugar . graphics . toolbarbox import ToolbarButton 

from sugar . activity . widgets import StopButton 

from toolbar import ViewToolbar 

from mybutton import MyActivityToolbarButton 
except : 

_NEW_TOOLBAR_SUPPORT = False 

from toolbar import ReadToolbar, ViewToolbar 



from sugar . graphics . toggletoolbutton import ToggleToolButton 



211 



from sugar . graphics .menuitem import Menultem 

from sugar . graphics import style 

from sugar import network 

from sugar . datastore import datastore 

from sugar . graphics . alert import NotifyAlert 

from gettext import gettext as _ 

page=0 

PAGE_SIZE =45 
TOOLBAR_READ = 2 

logger = logging . getLogger (' read-etexts2-activity ' ) 

class ReadHTTPRequestHandler ( 

network. Chun kedGlibHTTPRe que st Handler) : 

"""HTTP Request Handler for transferring document while 

collaborating. 

RequestHandler class that integrates with Glib mainloop. 
It writes the specified file to the client in chunks, 
returning control to the mainloop between chunks . 



def translate_path (self , path): 

"""Return the filepath to the shared document.""" 
return self . server . filepath 



class ReadHTTPServer (network. GlibTCPServer) : 

"""HTTP Server for transferring document while 

collaborating. """ 

def init (self, server_address , filepath) : 

"""Set up the GlibTCPServer with the 

ReadHTTPRequestHandler . 

filepath -- path to shared document to be served. 
ii ii ii 

self . filepath = filepath 

network. GlibTCPServer . init (self, 

server address, 

ReadHTTPRequestHandler) 



class ReadURLDownloader (network . GlibURLDownloader) : 
" " "URLDownloader that provides content-length 
and content-type.""" 

def get_content_length (self ) : 

"""Return the content-length of the download.""" 
if self._info is not None: 

return int (self. _inf o . headers. get ( 
'Content-Length' ) ) 

def get_content_type (self ) : 

"""Return the content-type of the download.""" 
if self._info is not None: 

return self. _info. headers. get ( 'Content-type') 
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return None 

READ_STREAM_SERVICE = ' read-etexts-activity-http ' 

class ReadEtextsActivity (activity .Activity) : 

def init (self, handle) : 

"The entry point to the Activity" 

global page 

activity .Activity . init (self, handle) 

self . f ileserver = None 

self . ob j ect_id = handle . obj ect_id 

if _NEW_TOOLBAR_SUPPORT: 

self . create_new_toolbar ( ) 
else : 

self . create_old_toolbar ( ) 

self . scrolled_window = gtk . ScrolledWindow ( ) 

self. scrolled_window. set_policy (gtk. POLICY_NEVER, 

gtk. POLICY_AUTOMATIC) 
self . scrolled_window .props . shadow_type = \ 

gtk.SHADOW_NONE 

self . textview = gtk . TextView ( ) 
self .textview. set_edi table (False) 
self. textview. set_cursor_visible (False) 
self. textview. set_lef t_margin (50 ) 
self. textview. connect ( "keypressevent" , 
self . keypress_cb) 

self . progressbar = gtk . ProgressBar ( ) 
self.progressbar. set_orientation ( 

gtk.PROGRESS_LEFT_TO_RIGHT) 
self. progressbar. set_fraction (0 . 0) 

self . scrolled_window . add (self. textview) 

self. textview. show () 

self . scrolled_window . show ( ) 

vbox = gtk.VBox() 

vbox . pack_start (self. progressbar, False, 

False, 10) 
vbox . pack_start ( self . scrolled_window) 
self . set_canvas (vbox) 
vbox . show ( ) 

page = 

self . clipboard = gtk . Clipboard ( 

display=gtk . gdk . display_get_def ault () , 

select ion=" CLIPBOARD") 
self . textview . grab_focus () 
self . f ont_desc = pango . FontDescription ( 

"sans %d" % style . zoom ( 10 ) ) 
self. textview . modif y_f ont (self . f ont_desc) 

buffer = self . textview . get_buffer ( ) 

self .markset id = buff er . connect ( "mark-set" , 
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self .mark_set_cb) 

self . unused_download_tubes = set () 

self . want_document = True 

self . download_content_length = 

self . download_content_type = None 

# Status of temp file used for write_file: 

self . tempf ile = None 

self . close_requested = False 

self. connect ("shared", self. shared_cb) 

self . is_received_document = False 

if self ._shared_activity and \ 
handle . obj ect_id == None: 

# We're joining, and we don't already have 

# the document. 

if self . get_shared ( ) : 

# Already joined for some reason, 

# just get the document 
self . j oined_cb (self) 

else : 

# Wait for a successful join before 

# trying to get the document 

self. connect ("joined", self.j oined_cb) 

def create_old_toolbar (self ) : 

toolbox = activity . ActivityToolbox (self ) 
activity_toolbar = toolbox . get_activity_toolbar ( ) 
activity_toolbar . keep .props . visible = False 

self . edit_toolbar = activity . EditToolbar ( ) 
self . edit_toolbar . undo .props .visible = False 
self . edit_toolbar . redo .props .visible = False 
self . edit_toolbar . separator .props . visible = False 
self . edit_toolbar . copy . set_sensitive (False) 
self . edit_toolbar .copy. connect ( 'clicked' , 

self . edit_toolbar_copy_cb) 
self . edit_toolbar .paste .props .visible = False 
toolbox . add_toolbar (_ ( ' Edit ' ) , self. edit_toolbar ) 
self . edit_toolbar . show ( ) 

self . readtoolbar = ReadToolbar ( ) 

toolbox . add_toolbar (_ ( ' Read' ) , self. read_toolbar ) 

self . readtoolbar .back. connect ( 'clicked' , 

self . go_back_cb) 
self . readtoolbar . forward. connect ( 'clicked' , 

self . go_f orward_cb) 
self . read_toolbar . num_page_entry .connect ( 'activate' , 

self . num_page_entry_activate_cb) 
self . readtoolbar . show ( ) 

self . view_toolbar = ViewToolbar ( ) 

toolbox . add_toolbar (_ ( ' View ' ) , self. view_toolbar ) 

self . view_toolbar .connect ( 'go-fullscreen' , 

self . view_toolbar_go_f ullscreen_cb) 
self . view_toolbar . zoom_in .connect ( 'clicked' , 

self. zoom in cb) 
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self . view_toolbar . zoom_out .connect ( 'clicked' , 

self . zoom_out_cb) 
self . view_toolbar . show ( ) 

self . set_toolbox (toolbox) 

toolbox . show ( ) 

self. toolbox. set_current_toolbar (TOOLBAR_READ) 

def create_new_toolbar (self ) : 
toolbar_box = ToolbarBox ( ) 

activity_button = MyActivityToolbarButton (self ) 
toolbar_box .toolbar. insert (activity_button, ) 
activity_button . show ( ) 

self . edit_toolbar = activity . EditToolbar ( ) 
self . edit_toolbar . undo .props . visible = False 
self . edit_toolbar . redo .props . visible = False 
self . edit_toolbar . separator .props . visible = False 
self . edit_toolbar . copy . set_sensitive (False) 
self . edit_toolbar .copy. connect ( 'clicked' , 

self . edit_toolbar_copy_cb) 
self . edit_toolbar . paste .props . visible = False 

edit_toolbar_button = ToolbarButton ( 

page=self. edit_toolbar , 

icon_name= ' toolbar-edit ' ) 
self . edit_toolbar . show ( ) 

toolbar_box .toolbar. insert (edit_toolbar_button, -1 ) 
edit_toolbar_button . show ( ) 

self . view_toolbar = ViewToolbar ( ) 

self . view_toolbar .connect ( 'go-fullscreen' , 

self . view_toolbar_go_f ullscreen_cb) 
self . view_toolbar . zoom_in .connect ( 'clicked' , 

self . zoom_in_cb) 
self . view_toolbar . zoom_out .connect ( 'clicked' , 

self . zoom_out_cb) 
self . view_toolbar . show ( ) 
view_toolbar_button = ToolbarButton ( 

page=self. view_toolbar , 

icon_name= ' toolbar-view ' ) 
toolbar_box .toolbar. insert (view_toolbar_button, -1 ) 
view_toolbar_button . show ( ) 

self. back = ToolButton (' go-previous ' ) 

self. back. set_tooltip (_ ( ' Back ' ) ) 

self . back . props . sensitive = False 

self. back. connect ( 'clicked' , self. go_back_cb) 

toolbar_box .toolbar. insert (self. back, -1) 

self. back. show ( ) 

self. forward = ToolButton (' go-next ' ) 
self. forward. set_tooltip (_( 'Forward')) 
self . forward. props . sensitive = False 
self. forward. connect ( 'clicked' , 

self . go_f orward_cb) 
toolbar box . toolbar . insert (self . forward, -1) 
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self. forward. show () 

num_page_item = gtk. Toolltem ( ) 

self . num_page_entry = gtk.EntryO 

self . num_page_entry . set_text ( ' ' ) 

self . num_page_entry . set_alignment ( 1 ) 

self . num_page_entry .connect ( ' insert-text' , 

self . new_num_page_entry_insert_text_cb) 

self . num_page_entry .connect ( 'activate' , 

self . new_num_page_entry_activate_cb) 

self . num_page_entry . set_width_chars (4 ) 

num_page_item. add (self . num_page_entry) 

self . num_page_entry . show ( ) 

toolbar_box .toolbar. insert (num_page_item, -1 ) 

num_page_item. show ( ) 

total_page_item = gtk . Toolltem ( ) 
self . total_page_label = gtk. Label () 

label_attributes = pango . AttrList ( ) 
label_attributes .insert (pango . AttrSize ( 

14000, 0, -1)) 
label_attributes .insert (pango. At tr Foreground ( 

65535, 65535, 65535, 0, -1)) 
self . total_page_label . set_at tributes ( 

label_attributes) 

self . total_page_label . set_text ( ' / 0') 
total_page_item. add (self . total_page_label ) 
self . total_page_label . show ( ) 

toolbar_box .toolbar. insert (total_page_item, -1 ) 
total_page_item. show ( ) 

separator = gtk . SeparatorToolItem ( ) 

separator . props . draw = False 

separator. setexpand (True) 

toolbar_box .toolbar. insert (separator, -1) 

separator. show () 

stop_button = StopButton (self ) 

stop_button .props . accelerator = ' <Ctrl><Shif t>Q ' 
toolbar_box .toolbar. insert (stop_button, -1 ) 
stop_button . show ( ) 

self . set_toolbar_box (toolbar_box) 
toolbar_box . show ( ) 

def new_num_page_entry_insert_text_cb (self , entry, 

text, length, position) : 

if not re. match (' [0-9] ' , text): 

entry. emit_stop_by_name ('insert-text') 

return True 
return False 

def new_num_page_entry_activate_cb (self , entry) : 

global page 

if entry . props . text : 

new_page = int (entry .props . text ) - 1 
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else : 

new_page = 

if new_page >= self . total_pages : 

new_page = self . total_pages - 1 

elif new_page < 0: 
new_page = 

self . current_page = newpage 

self . set_current_page (new_page) 

self . show_page (new_page) 

entry. props . text = str (newpage + 1) 

self . update_nav_buttons () 

page = new_page 

clef update_nav_buttons (self ) : 

current page = self. current page 

self . back . props . sensitive = current_page > 

self . forward. props . sensitive = \ 

current_page < self . total_pages - 1 

self . num_page_entry . props . text = str ( 

current_page + 1) 
self . total_page_label .props . label = \ 

' / ' + str ( self . total_pages) 

clef set_total_pages ( self , pages): 
self . total_pages = pages 

def set_current_page ( self , page): 
self . current_page = page 
self . update_nav_buttons () 

def keypress_cb ( self , widget, event): 

"Respond when the user presses one of the \ 

arrow keys" 

keyname = gtk . gdk . keyval_name (event . keyval) 

print keyname 

if keyname == 'plus' : 

self . f ont_increase ( ) 

return True 
if keyname == 'minus' : 

self . f on t_de crease ( ) 

return True 
if keyname == ' Page_Up ' : 

self . page_previous () 

return True 
if keyname == ' Page_Down ' : 

self . page_next ( ) 

return True 
if keyname == 'Up' or keyname == ' KP_Up ' \ 
or keyname == 'KP_Left' : 

self . scroll_up ( ) 

return True 
if keyname == 'Down' or keyname == ' KP_Down ' \ 
or keyname == 'KP_Right' : 

self . scroll_down ( ) 

return True 
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return False 

def num_page_entry_activate_cb (self , entry) : 
global page 
if entry . props . text : 

new_page = int (entry .props . text ) - 1 
else : 

new_page = 

if new_page >= self . read_toolbar . total_pages : 

new_page = self . readtoolbar . total_pages - 1 

elif new_page < 0: 
new_page = 

self . readtoolbar . current_page = newpage 

self . readtoolbar . set_current_page (new_page) 

self . show_page (new_page) 

entry . props . text = str (newpage + 1) 

self . readtoolbar . update_nav_buttons ( ) 

page = newpage 

def go_back_cb (self , button) : 
self . page_previous () 

def go_f orward_cb (self , button): 
self . page_next () 

def page_previous (self ) : 
global page 
page=page-l 
if page < 0: page=0 
if _NEW_TOOLBAR_SUPPORT: 

self . set_current_page (page) 
else : 

self . readtoolbar . set_current_page (page) 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . upper - \ 

v_adj ustment .page_size 

def page_next ( self ) : 
global page 
page=page+l 

if page >= len (self .page_index) : page=0 
if _NEW_TOOLBAR_SUPPORT: 

self . set_current_page (page) 
else : 

self . read_toolbar . set_current_page (page) 
self . show_page (page) 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
v_adj ustment . value = v_adjustment . lower 

def zoom_in_cb (self , button) : 
self . f ont_increase ( ) 

def zoom_out_cb (self , button) : 
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self . f on t_de crease ( ) 

def f ont_decrease ( self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size - 1 
if font_size < 1: 
font_size = 1 
self . f ont_desc . set_size ( f ont_size * 1024) 
self .textview . modif y_f ont (self . f ont_desc) 

def f ont_increase ( self ) : 

font_size = self . f ont_desc . get_size ( ) / 1024 
font_size = font_size + 1 

self . f ont_desc . set_size ( f ontsize * 1024) 
self. textview .modif y_f ont (self . f ont_desc) 

def raark_set_cb (self, textbuffer, iter, textmark) : 

if textbuf f er . get_has_selection ( ) : 

begin, end = textbuf fer . get_selection_bounds ( ) 
self . edit_toolbar . copy . set_sensitive (True) 

else : 

self . edit_toolbar . copy . set_sensitive (False) 

def edit_toolbar_copy_cb (self , button): 

textbuffer = self . textview . get_buf fer ( ) 
begin, end = textbuf fer . get_selection_bounds ( ) 
copy_text = textbuf fer . get_text (begin, end) 
self. clipboard. set_text (copy_text ) 

def view_toolbar_go_f ullscreen_cb (self , view_toolbar ) : 
self. fullscreen () 



def scrolldown ( self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . upper - 
v_adj ustment .page_size: 
self . page_next ( ) 
return 
if v_adj ustment . value < v_adjustment . upper - \ 
v_adj ustment .page_size: 
new_value = v_adjustment . value + \ 

v_adj ustment . step_increment 
if new_value > v_adjustment . upper - \ 
v_adj ustment .page_size: 
new value = v adjustment . upper - \ 
v_adj ustment .page_size 
v adj ustment . value = new value 
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def scroll_up ( self ) : 
v_adj ustment = \ 

self . scrolled_window . get_vadj ustment ( ) 
if v_adj ustment . value == v_adjustment . lower : 

self . page_previous () 

return 
if v_adj ustment . value > v_adjustment . lower : 

new value = v adjustment . value - \ 
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v_adjustment . step_increment 
if new_value < v_adjustment . lower : 

new_value = v_adjustment . lower 
v adj ustment . value = new value 

def show_page ( self , pagenumber ) : 

global PAGE_SIZE, current_word 

position = self .page_index [page_number ] 

self . etext_f ile .seek (position) 

linecount = 

label_text = '\n\n\n' 

textbuffer = self . textview . get_buffer ( ) 

while linecount < PAGE_SIZE: 

line = self . etext_f ile . readline ( ) 
label_text = label_text + Unicode (line, 

'iso-8859-1' ) 
linecount = linecount + 1 

label_text = label_text + '\n\n\n' 

textbuffer. set_text (label_text ) 

self. textview. setbuffer (textbuffer) 

def save_extracted_f ile (self , zipfile, filename): 

"Extract the file to a temp directory for viewing" 
filebytes = zipfile . read ( filename) 
outfn = self .make_new_f ilename (filename) 
if (outfn == ' ' ) : 

return False 
f = open (os .path . j oin (self . get_activity_root () , 

' tmp ' , outfn) , ' w ' ) 
try : 

f. write (filebytes) 
finally: 

f . close ( ) 

def get_saved_page_number (self ) : 
global page 

title = self .metadata . get (' title ' , '') 
if title == ' ' or not title [ len (title) -1 ]. isdigit () : 

page = 
else : 

i = len(title) - 1 
newPage = ' ' 

while (titlefi] .isdigit() and i > 0) : 
newPage = title [i] + newPage 
i = i - 1 
if title [i] == ' P' : 

page = int (newPage) - 1 
else : 

# not a page number; maybe a volume number. 
page = 

def save_page_number (self ) : 
global page 

title = self .metadata . get (' title ' , '') 
if title == ' ' or not title [ len (title) -1 ]. isdigit ( ) 

title = title + ' P' + str(page + 1) 
else : 

i = len(title) - 1 
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while (title [i] .isdigit() and i > 0) : 

i = i - 1 
if title [i] == ' P' : 

title = title[0:i] + 'P' + str (page + 1) 
else : 

title = title + ' P' + str (page + 1) 
self .metadata [' title ' ] = title 

def read_f ile ( self , filename) : 
"Read the Etext file" 
global PAGE_SIZE, page 

tempfile = os . path . j oin (self . get_activity_root () , 

'instance', 'tmp%i' % time . time () ) 
os . link ( filename, tempfile) 
self . tempfile = tempfile 

if zipf ile . is_zipf ile ( filename) : 

self.zf = zipf ile . ZipFile ( filename, 'r') 
self . book_f iles = self . zf . namelist ( ) 
self . save_extracted_f ile (self . zf , 

self .book_filesT0] ) 
currentFileName = os .path . j oin ( 
self . get_activity_root () , 
' tmp ' , self .book_f iles [ ] ) 
else : 

currentFileName = filename 

self . etext_f ile = open (currentFileName, "r" ) 

self . page_index = [ ] 

pagecount = 

linecount = 

while self . etext_f ile : 

line = self . etext_f ile . readline ( ) 
if not line: 

break 
linecount = linecount + 1 
if linecount >= PAGE_SIZE: 

position = self . etext_f ile . tell ( ) 
self . page_index . append (position) 
linecount = 
pagecount = pagecount + 1 
if filename . endswith (". zip" ) : 

os . remove (currentFileName) 
self . get_saved_page_number ( ) 
self . show_page (page) 
if _NEW_TOOLBAR_SUPPORT: 

self . set_total_pages (pagecount + 1) 
self . set_current_page (page) 
else : 

self . read_toolbar . set_total_pages ( 

pagecount + 1) 
self . read_toolbar . set_current_page (page) 

# We've got the document, so if we're a shared 

# activity, offer it 
if self . get_shared ( ) : 

self. watch for tubes () 
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self . sharedocument ( ) 

def make_new_f ilename (self , filename) : 

partition_tuple = f ilename . rpartition ('/' ) 
return partition_tuple [ 2 ] 

def write_f ile (self , filename) : 

"Save meta data for the file." 
if self . is_received_document : 

# This document was given to us by someone, 

# so we have to save it to the Journal. 
self.etext_file.seek(0) 

filebytes = self . etext_f ile . read ( ) 
print ' saving shared document ' 
f = open ( filename, ' wb ' ) 
try : 

f .write (filebytes) 
finally: 

f . close ( ) 
elif self . tempf ile : 

if self . close_requested: 

os . link (self . tempf ile, filename) 
logger . debug ( 

"Removing temp file %s because " 
"we will close", 
self . tempf ile) 
os.unlink(self. tempf ile) 
self . tempf ile = None 
else : 

# skip saving empty file 
raise NotlmplementedError 

self .metadata [' activity ' ] = self . get_bundle_id ( ) 
self . save_page_number ( ) 

def can_close ( self ) : 

self . close_requested = True 
return True 

def j oined_cb ( self , also_self ) : 

"""Callback for when a shared activity is joined. 

Get the shared document from another participant. 
ii ii ii 

self . watch_f or_tubes () 

gob j ect . idle_add (self . get_document ) 

def get_document (self ) : 

if not self . want_document : 
return False 

# Assign a file path to download if one 

# doesn't exist yet 

if not self . _j obj ect . file_path : 

path = os .path . j oin (self . get_activity_root () , 
'instance', 'tmp%i' % time . time () ) 
else : 

path = self . _j obj ect . file_path 
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# Pick an arbitrary tube we can try to download 

# the document from 
try : 

tube_id = self . unused_download_tubes .pop ( ) 
except (ValueError, KeyError) , e: 
logger . debug ( 

'No tubes to get the document from ' 

'right now: %s ' , e) 
return False 

# Avoid trying to download the document 

# multiple times at once 
self . want_document = False 

gobj ect . idle_add ( self . download_document , 

tube_id, path) 
return False 

def download_document ( self , tube_id, path): 

chan = self ._shared_activity . telepathy_tubes_chan 
iface = chan [telepathy. CHANNEL_TYPE_TUBES] 
addr = if ace . AcceptStreamTube (tube_id, 

telepathy. S0CKET_ADDRESS_TYPE_IPV4 , 

telepathy. SOCKET_ACCESS_CONTROL_LOCALHOST, 

0, 

utf8_strings=True) 
logger . debug ( 

'Accepted stream tube: ' 

'listening address is %r', 

addr) 
assert isinstance (addr, dbus. Struct) 
assert len (addr) == 2 
assert isinstance (addr [ ] , str) 
assert isinstance (addr [ 1 ] , (int, long)) 
assert addr[l] > and addr[l] < 65536 
port = int (addr [1 ] ) 

self.progressbar. show () 
getter = ReadURLDownloader ( 

"http : //%s : %d/ document " 

% (addr [0] , port) ) 
getter. connect ("finished", 

self . download_result_cb, tube_id) 
getter. connect ("progress", 

self . download_progress_cb, tube_id) 
getter. connect ("error", 

self . download_error_cb, tube_id) 
logger . debug ( "Starting download to %s...", path) 
getter. start (path) 
self . download_content_length = \ 

getter . get_content_length ( ) 
self . download_content_type = \ 

getter . get_content_type ( ) 
return False 

def download_progress_cb (self , getter, 
bytes_downloaded, tube_id) : 
if self . download_content_length > 0: 
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logger . debug ( 

"Downloaded %u of %u bytes from tube %u. 
bytes_downloaded, 
self . download_content_length, 
tube_id) 
else : 

logger . debug ( 

"Downloaded %u bytes from tube %u...", 
bytes_downloaded, tube_id) 
total = self . download_content_length 
self . set_downloaded_bytes (bytes_downloaded, 

total) 
gtk . gdk . threads_enter ( ) 
while gtk . eventspending ( ) : 

gtk .main_iteration ( ) 
gtk.gdk.threads_leave () 

def set_downloaded_bytes (self , bytes, total): 
fraction = float (bytes) / float (total) 
self .progressbar.set_fraction (fraction) 
logger . debug ( "Downloaded percent", fraction) 

def clear_downloaded_bytes (self ) : 

self.progressbar.set_fraction(0.0) 
logger . debug ( "Cleared download bytes") 

def download_error_cb (self , getter, err, tube_id) : 
self . progressbar . hide () 
logger . debug ( 

"Error getting document from tube %u: %s", 

tube_id, err) 
self. alert (_(' Failure') , 

_( 'Error getting document from tube')) 
self . want_document = True 
self . download_content_length = 
self . download_content_type = None 
gob j ect . idle_add (self . get_document ) 

def download_result_cb (self , getter, tempfile, 
suggested_name, tube_id) : 

if self . download_content_type . startswith ( 
'text/html ' ) : 

# got an error page instead 
self . download_error_cb (getter, 

'HTTP Error', tube_id) 
return 

del self . unused_download_tubes 

self . tempfile = tempfile 
file_path = os .path . j oin ( 

self . get_activity_root () , 

'instance', ' %i ' % time . time () ) 
logger . debug ( 

"Saving file %s to datastore. . .", file_path) 
os . link (tempfile, file_path) 
self . j obj ect . file_path = file_path 
datastore . write (self . _j obj ect , 
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transf er_ownership=True) 

logger . debug ( "Got document %s (%s) from tube %u", 

tempfile, suggested name, tube_id) 
self . is_received_document = True 
self . read_f ile (tempfile) 
self . save ( ) 
self . progressbar . hide () 

def shared_cb ( self , activityid) : 

"""Callback when activity shared. 

Set up to share the document. 



# We initiated this activity and have now 

# shared it, so by definition we have the file, 
logger . debug ( 'Activity became shared') 

self . watch_f or_tubes () 
self . share_document ( ) 

def share_document ( self ) : 

"""Share the document.""" 
h = hash ( self ._activity_id) 
port = 1024 + Th % 64511) 
logger . debug ( 

'Starting HTTP server on port %d', port) 
self . f ileserver = ReadHTTPServer ( ( " " , port), 
self . tempfile) 

# Make a tube for it 

chan = self ._shared_activity . telepathy_tubes_chan 
iface = chan [telepathy. CHANNEL_TYPE_TUBES] 
self . f ileserver_tube_id = if ace . Of f erStreamTube ( 
READ_STREAM_SERVICE, 

U, 

telepathy. SOCKET_ADDRESS_TYPE_IPV4 , 

('127.0.0.1', dbus.UIntl6 (port) ) , 

telepathy . SOCKET_ACCESS_CONTROL_LOCALHOST, 0) 

def watch_f or_tubes ( self ) : 

"""Watch for new tubes.""" 
tubes_chan = \ 

self . _shared_activity . telepathy_tubes_chan 

tubes_chan [telepathy . CHANNEL_TYPE_TUBES] . \ 

connect_to_signal ( 

'NewTube ' , 

self . new_tube_cb) 
tubes_chan [telepathy . CHANNEL_TYPE_TUBES] .ListTubes ( 

reply_handler=self . list_tubes_reply_cb, 

error_handler=self . list_tubes_error_cb) 

def new_tube_cb ( self , tube_id, initiator, tube_type, 
service, params, state) : 

"""Callback when a new tube becomes available.""" 
logger . debug ( 

'New tube: ID=%d initator=%d type=%d service=%s 
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'params=%r state=%d', tube_id, 
initiator, tube_type, 
service, params, state) 
if service == READ_STREAM_SERVICE : 

logger . debug (' I could download from that tube') 
self . unused_download_tubes . add (tube_id) 

# if no download is in progress, let's 

# fetch the document 
if self . want_document : 

gob j ect . idle_add (self . get_document ) 

def list_tubes_reply_cb (self , tubes): 

"""Callback when new tubes are available.""" 
for tube_info in tubes: 

self . new_tube_cb ( *tube_inf o) 

def list_tubes_error_cb (self , e): 

"""Handle ListTubes error by logging.""" 
logger . error (' ListTubes ( ) failed: %s ' , e) 

def alert (self, title, text=None) : 
alert = Notif yAlert (timeout=20 ) 
alert . props . title = title 
alert . props .msg = text 
self . add_alert (alert) 

alert. connect ( 'response', self. alert_cancel_cb) 
alert . show ( ) 

def alert_cancel_cb (self , alert, response_id) : 
self . remove_alert (alert) 
self . textview . grab_f ocus () 
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Here is what it looks like running under sugar-jhbuild: 




the most of it." 

Mr. Wickham's society mas of material service in dispelling the gloom 
which trie late perverse occurrences had thrown on many of the Longbourn 
family They saw him often, and to his other recommendations was now 
added that of general unreserve, The whole of what Elizabeth had already 
heard, his claims on Mr. Darcy, and all that he had suffered from him, 
was now openly acknowledged and publicly canvassed; and everybody was 
pleased to know how much they had always disliked Mr Darcy before they 
had known anything of the matter. 

Miss Bennet was the only creature who could suppose there might be 
any extenuating circumstances in the case, unknown to the society 
of Hertfordshire; her mild and steady candour always pleaded for 
allowances, and urged the possibility of mistakes--but by everybody else 
Mr. Darcy was condemned as the worst of men. 



Let's have a look at how it works. ! If you've paid attention to other chapters when I've 
talked about the idea of "degrading gracefully" the imports in this code will be about 
what you would expect: 

_NEW_TOOLBAR_SUPPORT = True 
try : 

from sugar . graphics . toolbarbox import ToolbarBox 

from sugar . graphics . toolbarbox import ToolbarButton 

from sugar . activity . widgets import StopButton 

from toolbar import ViewToolbar 

from mybutton import MyActivityToolbarButton 
except : 

_NEW_TOOLBAR_SUPPORT = False 

from toolbar import ReadToolbar , ViewToolbar 

Here we try to import a bunch of stuff that only exists in versions of Sugar that support 
the new toolbars. If we succeed, then _NEW_TOOLBAR_SUPPORT will remain set to 
True. If any of the imports fail then the variable is set to False. Note that a couple of 
imports that should always succeed are placed after the three that might fail. If any of 
the first three fail I don't want these imports to be done. 

This next bit of code in the init () method should not be surprising: 

if _NEW_TOOLBAR_SUPPORT: 

self . createnewtoolbar ( ) 
else : 
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self . create_old_toolbar ( ) 

I moved creating the toolbars into their own methods to make it easier to compare how 
the two different toolbars are created. The old toolbar code is unchanged. Here is the 
new toolbar code: 

def create newtoolbar (self ) : 
toolbar_box = ToolbarBox ( ) 

activity_button = MyActivityToolbarButton (self ) 
toolbar_box .toolbar. insert (activity_button, ) 
activity_button . show ( ) 

self . edit_toolbar = activity . EditToolbar ( ) 
self . edit_toolbar . undo .props .visible = False 
self . edit_toolbar . redo .props .visible = False 
self . edit_toolbar . separator .props . visible = False 
self . edit_toolbar . copy . set_sensitive (False) 
self . edit_toolbar .copy. connect ( 'clicked' , 

self . edit_toolbar_copy_cb) 
self . edit_toolbar .paste .props .visible = False 

edit_toolbar_button = ToolbarButton ( 

page=self. edit_toolbar , 

icon_name= ' toolbar-edit ' ) 
self . edit_toolbar . show ( ) 

toolbar_box .toolbar. insert (edit_toolbar_button, -1 ) 
edit_toolbar_button . show ( ) 

self . view_toolbar = ViewToolbar ( ) 

self . view_toolbar .connect ( 'go-fullscreen' , 

self . view_toolbar_go_f ullscreen_cb) 
self . view_toolbar . zoom_in .connect ( 'clicked' , 

self . zoom_in_cb) 
self . view_toolbar . zoom_out .connect ( 'clicked' , 

self . zoom_out_cb) 
self . view_toolbar . show ( ) 
view_toolbar_button = ToolbarButton ( 

page=self. viewtoolbar, 

icon_name= 'toolbar-view' ) 
toolbar_box .toolbar. insert ( 

view_toolbar_button, -1) 
view_toolbar_button . show ( ) 

self. back = ToolButton (' go-previous ' ) 

self. back. set_tooltip (_ ( ' Back ' ) ) 

self . back . props . sensitive = False 

self. back. connect ( 'clicked' , self. go_back_cb) 

toolbar_box .toolbar. insert (self. back, -1) 

self . back . show ( ) 

self. forward = ToolButton (' go-next ' ) 
self. forward. set_tooltip (_( 'Forward')) 
self . forward. props . sensitive = False 
self. forward. connect ( 'clicked' , 

self . go_f orward_cb) 
toolbar_box .toolbar. insert (self. forward, -1) 
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self. forward. show () 

num_page_item = gtk . Toolltem ( ) 

self . nura_page_entry = gtk. Entry () 

self . num_page_entry . set_text ( ' ' ) 

self . num_page_entry . set_alignment ( 1 ) 

self . num_page_entry .connect ( ' insert-text' , 

self . new_num_page_entry_insert_text_cb) 

self . num_page_entry .connect ( 'activate' , 

self . new_num_page_entry_activate_cb) 

self . num_page_entry . set_width_chars (4 ) 

num_page_item. add ( self . num_page_entry) 

self . num_page_entry . show ( ) 

toolbar_box .toolbar. insert (num_page_item, -1 ) 

num_page_item . show ( ) 

total_page_item = gtk . Toolltem ( ) 
self . total_page_label = gtk. Label () 

label_attributes = pango . AttrList ( ) 
label_attributes .insert (pango . AttrSize ( 

14000, 0, -1)) 
label_attributes .insert (pango . At tr Foreground ( 

65535, 65535, 65535, 0, -1)) 
self . total_page_label . set_at tributes ( 

label_attributes) 

self . total_page_label . set_text ( ' / 0') 
total_page_item. add (self . total_page_label ) 
self . total_page_label . show ( ) 

toolbar_box .toolbar. insert (total_page_item, -1 ) 
total_page_item. show ( ) 

separator = gtk . SeparatorToolItem ( ) 

separator . props . draw = False 

separator. set_expand (True) 

toolbar_box .toolbar. insert (separator, -1) 

separator . show ( ) 

stop_button = StopButton (self ) 

stop_button . props . accelerator = ' <Ctrl><Shif t>Q ' 
toolbar_box .toolbar. insert (stop_button, -1 ) 
stop_button . show ( ) 

self . set_toolbar_box (toolbar_box) 
toolbar_box . show ( ) 

def new_num_page_entry_insert_text_cb (self , entry, 

text, length, position) : 

if not re .match ('[ 0-9] ' , text): 

entry. emit_stop_by_name ('insert-text') 

return True 
return False 

def new_num_page_entry_activate_cb (self , entry) : 

global page 

if entry . props . text : 

new_page = int (entry .props . text ) - 1 
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else : 

new_page = 

if new_page >= self . total_pages : 

new_page = self . total_pages - 1 
elif new_page < 0: 

new_page = 

self . current_page = newpage 

self . set_current_page (new_page) 

self . show_page (new_page) 

entry . props . text = str (newpage + 1) 

self . update navbuttons ( ) 

page = newpage 

def update_nav_buttons (self ) : 

current page = self. current page 

self . back . props . sensitive = current_page > 

self . forward. props . sensitive = \ 

current_page < self . total_pages - 1 

self . num_page_entry .props . text = str ( 

current_page + 1) 
self . total_page_label .props . label = \ 

' / ' + str (self . total_pages ) 

def set_total_pages (self , pages): 
self . total_pages = pages 

def set_current_page (self , page): 
self . current_page = page 
self . update_nav_buttons ( ) 

Much of the code in the two methods is the same. In particular, the View toolbar and 
the Edit toolbar are exactly the same in both. Instead of becoming the active toolbar 
they drop down from the toolbar to become sub toolbars. If we had done the Read 
toolbar the same way we could have implemented both old and new toolbars with very 
little code. However, the Read toolbar contains controls that are important enough to 
the Activity that they should be available at all times, so we put them in the main 
toolbar instead. Because of this every place where the code refers to the Read toolbar 
has to have two ways it can be performed, like this: 

if _NEW_TOOLBAR_SUPPORT: 

self . set_total_pages (pagecount + 1) 

self . set_current_page (page) 
else : 

self . read_toolbar . set_total_pages ( 
pagecount + 1) 

self . readtoolbar . set_current_page (page) 

There is one more point of interest when it comes to the main toolbar. When you have 
an old style toolbar you get the stop button as part of the Activity toolbar. With the 
new style toolbar you need to add it to the end of the main toolbar yourself: 
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separator = gtk . SeparatorToolItem ( ) 

separator . props . draw = False 

separator . set_expand (True) 

toolbar_box .toolbar. insert (separator, -1) 

separator . show ( ) 

stop_button = StopButton (self ) 

stop_button . props . accelerator = ' <Ctrl><Shif t>Q ' 
toolbar_box .toolbar. insert (stop_button, -1 ) 
stop_button . show ( ) 

Note that you must put a gtk.SeparatorToolItem with set_expand() equal to True 
before the StopButton. This will push the button all the way to the right of the toolbar, 
where it belongs. 

That just leaves the Activity toolbar to discuss: 

toolbar_box = ToolbarBox ( ) 

activity_button = MyActivityToolbarButton (self ) 
toolbar_box .toolbar. insert (activity_button, ) 
activity_button . show ( ) 

Normally you would use the class ActivityToolbarButton to create the default drop 
down Activity toolbar. The problem I have with that is if I do that there is no way to 
hide the Keep button or the Share control. This version of the Activity needs the 
Share control, but has no use at all for the Keep button. 

There have been some spirited discussions about the Keep button on the mailing lists. 
New computer users don't know what it's for, and experienced computer users expect it 
to be like a Save Game button or a Save As... menu option in a regular application. It 
isn't quite like either one, and that can lead to confusion. For these reasons I've decided 
that no Activity of mine will leave the Keep button unhidden. To hide the button I 
copied a bit of the code for the original ActivityToolbarButton in a file named 
mybutton.py: 

import gtk 
import gconf 

from sugar . graphics . toolbarbox import ToolbarButton 

from sugar . activity . widgets import ActivityToolbar 

from sugar . graphics . xocolor import XoColor 

from sugar . graphics . icon import Icon 

from sugar . bundle . activitybundle import ActivityBundle 

def _create_activity_icon (metadata) : 

if metadata . get (' icon-color ' , ''): 

color = XoColor (metadata [' icon-color '] ) 
else : 

client = gconf . client_get_def ault ( ) 
color = XoColor (client . get_string ( 
'/desktop/sugar/user/color')) 
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from sugar . activity . activity import get_bundle_path 

bundle = ActivityBundle (get_bundle_path ( ) ) 

icon = Icon ( f ile=bundle . get_icon ( ) , xo_color=color ) 

return icon 

class MyActivityToolbarButton (ToolbarButton) : 

def init (self, activity, **kwargs) : 

toolbar = ActivityToolbar (activity, 

orientation_lef t=True) 
toolbar. stop. hide () 
toolbar . keep . hide ( ) 

ToolbarButton . init (self, page=toolbar, 

**kwargs) 

icon = _create_activity_icon (activity . metadata) 
self . set_icon_widget (icon) 
icon . show ( ) 

The line in bold is the one difference between mine and the original. If toolbar had 
been made an instance variable (self.toolbar) I could have used the original class. 
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ZCK Where To Go From Here? 



This book attempts to give a beginning programmer the information she needs to 
develop and publish her own Sugar Activities. It already contains many URL's of 
websites containing information not covered in the book. This chapter will contain 
URL's and pointers to still more resources that will be useful to any Sugar developer. 

PyGTK Book by Peter Gill 

Much of the work you will do writing Activities involves PyGTK. Peter Gill is working 
on a PyGTK book that covers the subject in great detail. You can download the book 
here: 

http://www.majorsilence.com/PyGTK B ook 

OLPC Austria Activity Handbook 

This is the first attempt to write a manual on creating Sugar Activities. It is aimed at 
experienced programmers and covers topics that this book does not, like how to write 
Activities using languages other than Python. The book was written in 2008 and as a 
result some of the advice is a bit dated. It's still an excellent source of information. The 
authors are Christoph Derndorfer and Daniel Jahre. 

http://wiki.sugarlabs.Org/images/5/51/Activity Handbook 200805 online.pdf 

http : //www, olpcaustria. org 

The Sugar Almanac 

This is a series of Wiki articles covering the Sugar API (Application Programming 
Interface). It's a good source of information that I have referred to many times. 

http://wiki.sugarlabs.org/go/Development Team/Almanac 



234 



Sugar Labs Mailing Lists 

Sugar Labs has several email mailing lists that might be worth subscribing to. The ones 
I follow most are the IAEP (It's An Education Proiject) list and Sugar-Devel. Sugar- 
Devel is a good place to ask questions about developing Sugar Activities and learn 
about the latest work being done on Sugar itself. IAEP is a good place to get ideas on 
what kinds of Activities teachers and students want and to get feedback on your own 
Activities. Anyone can sign up to these mailing lists here: 

http://lists.sugarlabs.org/ 

PyDoc 

PyDoc is a utility for viewing documentation generated from the Python libraries on 
your computer, including the Sugar libraries. To run it use this command from a 
terminal: 

pydoc -p 1234 

This command will not finish. It runs a kind of web server on your system where 1234 
is a port number. You can access the website it serves at http://localhost:1234. There 
is nothing magic about the number 1234. You can use any number you like. 

The website lets you follow links to documentation on all the Python libraries you have 
installed. When you are done browsing the documentation you can stop the pydoc 
command bt returning to the terminal and hitting Ctrl-C (hold down the Ctrl key and hit 
the "c" key). 
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22. 



License 



All chapters copyright of the authors (see below). Unless otherwise stated all chapters in 
this manual licensed with GNU General Public License version 2 

This documentation is free documentation; you can redistribute it and/or modify it 
under the terms of the GNU General Public License as published by the Free Software 
Foundation; either version 2 of the License, or (at your option) any later version. 

This documentation is distributed in the hope that it will be useful, but WITHOUT 
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 
more details. 

You should have received a copy of the GNU General Public License along with this 
documentation; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, 
Fifth Floor, Boston, MA 02110-1301, USA. 
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□ 



FLOSS 

MANUALS 



Free manuals for free software 



General Public License 

Version 2, June 1991 

Copyright (Q 1989, 1991 Free Software Foundation, Inc. 

51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 

Everyone is permitted to copy and distribute verbatim copies 
of this license document, but changing it is not allowed. 

Preamble 

The licenses for most software are designed to take away your freedom to share and 
change it. By contrast, the GNU General Public License is intended to guarantee your 
freedom to share and change free software—to make sure the software is free for all its 
users. This General Public License applies to most of the Free Software Foundation's 
software and to any other program whose authors commit to using it. (Some other Free 
Software Foundation software is covered by the GNU Lesser General Public License 
instead.) You can apply it to your programs, too. 
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When we speak of free software, we are referring to freedom, not price. Our General 
Public Licenses are designed to make sure that you have the freedom to distribute 
copies of free software (and charge for this service if you wish), that you receive source 
code or can get it if you want it, that you can change the software or use pieces of it in 
new free programs; and that you know you can do these things. 

To protect your rights, we need to make restrictions that forbid anyone to deny you 
these rights or to ask you to surrender the rights. These restrictions translate to certain 
responsibilities for you if you distribute copies of the software, or if you modify it. 

For example, if you distribute copies of such a program, whether gratis or for a fee, you 
must give the recipients all the rights that you have. You must make sure that they, too, 
receive or can get the source code. And you must show them these terms so they know 
their rights. 

We protect your rights with two steps: (1) copyright the software, and (2) offer you this 
license which gives you legal permission to copy, distribute and/or modify the software. 

Also, for each author's protection and ours, we want to make certain that everyone 
understands that there is no warranty for this free software. If the software is modified 
by someone else and passed on, we want its recipients to know that what they have is 
not the original, so that any problems introduced by others will not reflect on the 
original authors' reputations. 

Finally, any free program is threatened constantly by software patents. We wish to 
avoid the danger that redistributors of a free program will individually obtain patent 
licenses, in effect making the program proprietary. To prevent this, we have made it 
clear that any patent must be licensed for everyone's free use or not licensed at all. 

The precise terms and conditions for copying, distribution and modification follow. 

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND 
MODIFICATION 

0. This License applies to any program or other work which contains a notice placed by 
the copyright holder saying it may be distributed under the terms of this General Public 
License. The "Program", below, refers to any such program or work, and a "work based 
on the Program" means either the Program or any derivative work under copyright law: 
that is to say, a work containing the Program or a portion of it, either verbatim or with 
modifications and/or translated into another language. (Hereinafter, translation is 
included without limitation in the term "modification".) Each licensee is addressed as 
"you". 
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Activities other than copying, distribution and modification are not covered by this 
License; they are outside its scope. The act of running the Program is not restricted, and 
the output from the Program is covered only if its contents constitute a work based on 
the Program (independent of having been made by running the Program). Whether 
that is true depends on what the Program does. 

1. You may copy and distribute verbatim copies of the Program's source code as you 
receive it, in any medium, provided that you conspicuously and appropriately publish 
on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all 
the notices that refer to this License and to the absence of any warranty; and give any 
other recipients of the Program a copy of this License along with the Program. 

You may charge a fee for the physical act of transferring a copy, and you may at your 
option offer warranty protection in exchange for a fee. 

2. You may modify your copy or copies of the Program or any portion of it, thus 
forming a work based on the Program, and copy and distribute such modifications or 
work under the terms of Section 1 above, provided that you also meet all of these 
conditions: 



a) You must cause the modified files to carry prominent notices stating that you 
changed the files and the date of any change. 

b) You must cause any work that you distribute or publish, that in whole or in part 
contains or is derived from the Program or any part thereof, to be licensed as a 
whole at no charge to all third parties under the terms of this License. 

c) If the modified program normally reads commands interactively when run, you 
must cause it, when started running for such interactive use in the most ordinary 
way, to print or display an announcement including an appropriate copyright 
notice and a notice that there is no warranty (or else, saying that you provide a 
warranty) and that users may redistribute the program under these conditions, and 
telling the user how to view a copy of this License. (Exception: if the Program itself 
is interactive but does not normally print such an announcement, your work based 
on the Program is not required to print an announcement.) 
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These requirements apply to the modified work as a whole. If identifiable sections of 
that work are not derived from the Program, and can be reasonably considered 
independent and separate works in themselves, then this License, and its terms, do not 
apply to those sections when you distribute them as separate works. But when you 
distribute the same sections as part of a whole which is a work based on the Program, 
the distribution of the whole must be on the terms of this License, whose permissions 
for other licensees extend to the entire whole, and thus to each and every part regardless 
of who wrote it. 

Thus, it is not the intent of this section to claim rights or contest your rights to work 
written entirely by you; rather, the intent is to exercise the right to control the 
distribution of derivative or collective works based on the Program. 

In addition, mere aggregation of another work not based on the Program with the 
Program (or with a work based on the Program) on a volume of a storage or distribution 
medium does not bring the other work under the scope of this License. 

3. You may copy and distribute the Program (or a work based on it, under Section 2) in 
object code or executable form under the terms of Sections 1 and 2 above provided that 
you also do one of the following: 



a) Accompany it with the complete corresponding machine-readable source code, 
which must be distributed under the terms of Sections 1 and 2 above on a medium 
customarily used for software interchange; or, 

b) Accompany it with a written offer, valid for at least three years, to give any third 
party, for a charge no more than your cost of physically performing source 
distribution, a complete machine-readable copy of the corresponding source code, 
to be distributed under the terms of Sections 1 and 2 above on a medium 
customarily used for software interchange; or, 

c) Accompany it with the information you received as to the offer to distribute 
corresponding source code. (This alternative is allowed only for noncommercial 
distribution and only if you received the program in object code or executable form 
with such an offer, in accord with Subsection b above.) 
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The source code for a work means the preferred form of the work for making 
modifications to it. For an executable work, complete source code means all the source 
code for all modules it contains, plus any associated interface definition files, plus the 
scripts used to control compilation and installation of the executable. However, as a 
special exception, the source code distributed need not include anything that is normally 
distributed (in either source or binary form) with the major components (compiler, 
kernel, and so on) of the operating system on which the executable runs, unless that 
component itself accompanies the executable. 

If distribution of executable or object code is made by offering access to copy from a 
designated place, then offering equivalent access to copy the source code from the same 
place counts as distribution of the source code, even though third parties are not 
compelled to copy the source along with the object code. 

4. You may not copy, modify, sublicense, or distribute the Program except as expressly 
provided under this License. Any attempt otherwise to copy, modify, sublicense or 
distribute the Program is void, and will automatically terminate your rights under this 
License. However, parties who have received copies, or rights, from you under this 
License will not have their licenses terminated so long as such parties remain in full 
compliance. 

5. You are not required to accept this License, since you have not signed it. However, 
nothing else grants you permission to modify or distribute the Program or its derivative 
works. These actions are prohibited by law if you do not accept this License. Therefore, 
by modifying or distributing the Program (or any work based on the Program), you 
indicate your acceptance of this License to do so, and all its terms and conditions for 
copying, distributing or modifying the Program or works based on it. 

6. Each time you redistribute the Program (or any work based on the Program), the 
recipient automatically receives a license from the original licensor to copy, distribute or 
modify the Program subject to these terms and conditions. You may not impose any 
further restrictions on the recipients' exercise of the rights granted herein. You are not 
responsible for enforcing compliance by third parties to this License. 
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7. If, as a consequence of a court judgment or allegation of patent infringement or for 
any other reason (not limited to patent issues), conditions are imposed on you (whether 
by court order, agreement or otherwise) that contradict the conditions of this License, 
they do not excuse you from the conditions of this License. If you cannot distribute so 
as to satisfy simultaneously your obligations under this License and any other pertinent 
obligations, then as a consequence you may not distribute the Program at all. For 
example, if a patent license would not permit royalty-free redistribution of the Program 
by all those who receive copies directly or indirectly through you, then the only way 
you could satisfy both it and this License would be to refrain entirely from distribution 
of the Program. 

If any portion of this section is held invalid or unenforceable under any particular 
circumstance, the balance of the section is intended to apply and the section as a whole 
is intended to apply in other circumstances. 

It is not the purpose of this section to induce you to infringe any patents or other 
property right claims or to contest validity of any such claims; this section has the sole 
purpose of protecting the integrity of the free software distribution system, which is 
implemented by public license practices. Many people have made generous 
contributions to the wide range of software distributed through that system in reliance 
on consistent application of that system; it is up to the author/donor to decide if he or 
she is willing to distribute software through any other system and a licensee cannot 
impose that choice. 

This section is intended to make thoroughly clear what is believed to be a consequence 
of the rest of this License. 

8. If the distribution and/or use of the Program is restricted in certain countries either by 
patents or by copyrighted interfaces, the original copyright holder who places the 
Program under this License may add an explicit geographical distribution limitation 
excluding those countries, so that distribution is permitted only in or among countries 
not thus excluded. In such case, this License incorporates the limitation as if written in 
the body of this License. 

9. The Free Software Foundation may publish revised and/or new versions of the 
General Public License from time to time. Such new versions will be similar in spirit to 
the present version, but may differ in detail to address new problems or concerns. 
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Thanks for reading! 

Visit http://flossmanuals.net to make corrections or to find more manuals. 



